DocTreeFactory
DocTreeFactory (문서 주석 트리 노드 생성 팩토리)
javadoc 문서 주석을 나타내는 DocTree 노드를 만들어 내는 팩토리 인터페이스입니다. @author, @param, {@link} 같은 문서 주석의 각 요소를 프로그램적으로 생성할 때 사용해요.
본문
문서 주석은 텍스트만 있는 게 아니라 인라인 태그와 블록 태그로 이루어진 구조화된 트리입니다. 이 인터페이스는 그 트리를 구성하는 각종 노드를 일관된 방식으로 만들어 주는 팩토리 역할을 해요. 덕분에 사용자는 소스 텍스트를 직접 파싱하지 않고도 태그 하나하나를 DocTree 객체로 만들 수 있습니다.
구현상의 제약이 하나 있어요. 이 인터페이스의 구현체가 가진 메서드는 같은 구현체가 만든 DocTree 노드만 받아들일 수 있습니다. 서로 다른 구현에서 만든 노드를 섞어 쓰면 안 된다는 점을 기억해 두세요.
주요 메서드
-
at(int pos)— 이후 생성되는 트리 노드에 기록될 위치를 설정해요. 위치는 소스 파일 시작점을 기준으로 한 문자 오프셋이거나NOPOS입니다. 메서드 체이닝이 가능하도록this를 반환합니다. -
getFirstSentence(List<? extends DocTree> list)— 주어진 내용 목록에서 첫 문장을 추출해 반환해요. 첫 문장 판정은 구현별로 다를 수 있고, 로케일별BreakIterator같은 휴리스틱이 동원되기도 합니다. -
newDocCommentTree(...)— 문서 주석 전체를 나타내는DocCommentTree객체를 만듭니다. 본문 전체와 블록 태그 목록을 받는 형식과, 여기에 HTML 파일의 앞부분(premable)과 뒷부분(postamble)까지 받는 형식이 따로 있어요. -
각 태그용 팩토리 메서드 —
@author(newAuthorTree),@param(newParamTree),@return(newReturnTree),@see(newSeeTree),@throws(newThrowsTree),@deprecated(newDeprecatedTree) 같은 표준 태그부터{@link }(newLinkTree),{@literal }(newLiteralTree),{@code }(newCodeTree),{@snippet }(newSnippetTree) 같은 인라인 태그까지 문서 주석에서 쓰이는 대부분의 태그에 대응하는 생성 메서드가 준비되어 있어요. -
HTML 요소용 메서드 — 속성을 만드는
newAttributeTree, HTML 요소 시작·종료를 나타내는newStartElementTree/newEndElementTree, 엔티티를 나타내는newEntityTree등은 문서 주석 안에 포함된 HTML 구조를 표현할 때 사용됩니다.
몇몇 메서드는 기본 구현(default method)을 가지는데, 예를 들어 인라인 {@return } 태그를 지원하지 않는 구현은 newReturnTree(boolean, ...)에서 UnsupportedOperationException을 던집니다.