DocSourcePositions

DocSourcePositions (javadoc 주석 내 위치 제공)

javadoc 주석 안에 있는 DocTree의 위치를 알아내는 메서드를 제공하는 인터페이스입니다. 소스 코드에서 특정 노드가 어디서 시작하고 끝나는지 문자 오프셋 단위로 알 수 있어요.

출처: Java API Reference

본문

위치는 컴파일 단위(CompilationUnit)의 시작점에서 잰 단순한 문자 오프셋으로 정의됩니다. 첫 번째 문자가 오프셋 0인 방식이라, 파일 전체에서 해당 노드가 몇 번째 문자에서 시작하는지를 그대로 숫자로 돌려받는 구조예요. 이 인터페이스는 소스 코드 트리에 대한 일반 위치 정보를 제공하는 SourcePositions를 확장해, javadoc 주석(문서 주석) 안의 트리까지도 위치를 잴 수 있게 한 것이 특징입니다.

메서드

  • getStartPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree) — 지정한 트리가 주석 안에서 시작하는 위치를 반환해요. 파일 안에서 트리를 찾지 못했거나 시작 위치를 계산할 수 없으면 Diagnostic.NOPOS를 돌려줍니다. 이 메서드는 주어진 TreePath에 대해 DocTrees.getDocCommentTree(...)가 반환한 문서 주석 트리를 comment로 넘겨야 올바르게 동작해요. 반환되는 위치는 이 트리가 시작하는 지점이어야 하므로, 하위 트리가 있다면 시작 위치는 항상 하위 트리의 시작 위치보다 작거나 같아야 합니다(NOPOS인 경우 제외).

  • getEndPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree) — 트리가 주석 안에서 끝나는 위치를 반환해요. 못 찾거나 계산할 수 없으면 Diagnostic.NOPOS를 돌려줍니다. 종료 위치는 하위 트리의 종료 위치보다 크거나 같아야 하고, 같은 트리에 대해 시작 위치가 종료 위치보다 작거나 같아야 한다는 제약도 함께 확인해야 해요.

두 메서드의 위치 값은 위 조건들을 만족해야 하므로, 이 인터페이스를 구현할 때는 트리의 중첩 관계와 NOPOS 처리를 함께 고려해야 합니다. 특히 문서 주석은 소스 코드와 별개의 트리이므로, TreePath와 문서 주석 트리(DocCommentTree)를 함께 넘겨야 올바른 위치를 계산할 수 있어요.

이 위치 정보는 소스 코드를 다시 만드는 도구(reverse engineering)나 특정 태그의 소스 범위를 표시해야 하는 편집기 통합 같은 곳에서 유용하게 쓰입니다.

이 인터페이스는 DocTrees.getSourcePositions()를 통해 얻을 수 있어요. 문서 주석 트리와 소스 위치를 연결해 주는 DocTrees의 보조 도구라고 보면 이해하기 쉬워요.

더 알아보기

Java 공식 API