7. 문서화 (javadoc) 

7.1 서식(formatting)

1. 일반 서식 (General form)

Javadoc 블록의 기본적인 형식은 다음 예제에서 보는 것과 같습니다.

/**

 * Multiple lines of Javadoc text are written here,

 * wrapped normally...

 */

public int method(String p1) { ... }

또는 다음과 같은 하나의 라인으로 작성할 수 있습니다.

/** An especially short bit of Javadoc. */

기본적인 형식(basic form)은 항상 허용됩니다. Javadoc 블록 전체(주석 표시 포함)가 하나의 라인으로 작성할 수 있는 경우는 한 줄 형식으로 대체될 수 있습니다. @return과 같은 블록 태그가 없는 경우에만 해당됨을 유의하세요.

2. 단락(Paragraphs)

정렬된 선행 별표(aligned leading asterisk:’*’)만 포함하고 있는 하나의 빈 줄은 단락 사이와 블록 태그 그룹이 있을 경우 태그 그룹 앞에 나옵니다. 첫번째 단락을 제외한 각 단락은 첫번째 단어 바로 앞에 <p> 태그가 있고, 뒤에는 공백이 없습니다.

3. 블록 태그(Block tags)

코드에 사용하는 표준 “블록 태그(block tags)”는 @param, @return, @throws, @deprecated 순서로 사용되며, 이 4가지 유형은 설명이 비어 있으면 안 됩니다. 블록 태그가 한 줄에 맞지 않으면 @위치에서 4개 이상의 스페이스로 들여쓰기를 합니다.

7.2 요약 단편(the summary fragment)

각 Javadoc 블록은 간단한 요약 단편으로 시작합니다. 이 단편적인 요약은 매우 중요합니다.  클래스나 메서드 인덱스처럼 특별한 컨텍스트(context)에서 나타나는 텍스트의 유일한 부분입니다.

이 단편은 완전한 문장이 아니라 명사구나 동사 구절입니다. A {@code Foo}처럼 시작하지도 않고, “This method returns…”로 시작하지도 않고, “Save the rcord..”와 같은 완전한 명령형 문장의 형태로 시작하지도 않습니다. 하지만, 요약 단편에는 완전한 문장인 것처럼 대문자와 구두점이 있습니다.

Tip : 일반적으로 /** @return the customer ID */와 같이 Javadoc을 작성하는 실수를 하게 됩니다. 이것은 잘못된 것입니다. /** Returns the customer ID */처럼 변경해야 합니다.

7.3 Javadoc 사용처(where javadoc is used)

최소한, Javadoc은 모든 public class와 그 클래스에 있는 public, protected 멤버에 관해 존재하지만, 아래 언급된 몇 가지 예외가 있습니다.

아래 3번 Non-required Javadoc에 설명되어 있는 것처럼, 추가적인 Javadoc 컨텐츠가 있을 수 있습니다.

1. 예외(Exception) : 자체 서술적인 메서드 (self-explanatory methods)

getFoo와 같이 “단순하고 분명한(simple, obvious)” 메서드에 대해서 Javadoc을 작성하는 것은 선택 사항입니다. 이 경우처럼, “Returns the foo”라고 말하는 것 이외 아무것도 말할 가치가 없는 경우도 있습니다.

중요(important) : 일반적으로 독자가 알 필요가 있는 관련 정보를 생략하는 것을 정당화하기 위해 위에 언급된 예외를 적용하는 것은 적합하지 않습니다. 예를 들어, getCanonicalName의 메서드의 경우, 일반 독자가 “표준 이름(canonical name)”이라는 용어가 무엇을 의미하는지 모를 경우 해당 Javadoc 문서(단지 /** Returns the canonical name. */만을 말하고자 하는 이유일지라도)를 생략하면 안 됩니다.

2. 예외(Exception) : 재정의(override)

상위 유형(supertype) 메서드를 재정의하는 경우에는 항상 Javadoc이 존재하는 것은 아닙니다.

3. 불필요한 경우 (Non-required Javadoc)

다른 클래스와 멤버의 경우, 필요에 따라 Javadoc이 있습니다.

구현 주석(implementation comments)이 클래스나 멤버 전체의 목적이나 동작에 대해 정의하는데 사용되는 경우, 해당 주석은 Javadoc으로 작성될 수 있습니다. (/** 사용)

불필요한 경우의  Javadoc(non-required javadoc)은 위에서 정리한 단락(Paragraphs)이나 블록 태그(Block tags), 요약 단편(Summary fragments)의 형식을 따르도록 엄격하게 요구되지는 않지만, 될 수 있으면 정해진 형식을 따르기를 권고합니다.