[Effective Java] 아이템56 - 공개된 API 요소에는 항상 문서화 주석을 작성하라

Javadoc 유틸리티로 문서화 주석을 하는 방법에 대해 알아본다

메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.

• 클라이언트가 해당 메서드를 호출하기 위핸 전제조건
  • 보통 @throws 태그로 비검사 예외를 선언해서 암시적으로 기술한다.
  • @param 태그를 이용해서 영향받는 매개변수를 기술할 수 있다.
• 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건

JavaDoc 에 관련된 자세한 항목은 이 링크에서 잘 정리해놔서 첨부한다.

예제 소스코드를 javadoc 으로 만들어보기

클래스에 주석을 잘 적었다면 javadoc 명령어를 통해 javadoc 을 만들어보자. 나는 JavaDocTest.java 클래스 파일을 문서로 만들어 볼 것이다.

javadoc -private -d doc JavaDocTest.java

그런데 아래와 같은 오류가 나면서 @implSpec 에 대한 주석이 제대로 실행이 안됐다.

JavaDocTest.java:46: error: unknown tag: implSpec
     * @implSpec This implementation returns {@code this.size() == 0}.
       ^

책에 내용에서 자바11까지도 스위치를 켜주지 않으면 @implSpec 태그를 무시한다는 내용을 봤다. 커맨드라인에 아래 옵션을 적어줘야 실행이 된다.

-tag "implSpec:a:Implementation Requirements:"

수행을 하면 아래와 같은 파일들이 쭈욱 만들어지는 것을 확인할 수 있다. 그리고 우리는 만들어진 파일 중에 index.html 을 찾아서 열어보면 javadoc 이 만들어진 걸 확인할 수 있다!

Loading source file JavaDocTest.java...
Constructing Javadoc information...
Standard Doclet version 11.0.11
Building tree for all the packages and classes...
Generating doc/ch8/sunmin/item56/JavaDocTest.html...
Generating doc/ch8/sunmin/item56/JavaDocTest.ExceptionTest.html...
Generating doc/ch8/sunmin/item56/JavaDocTest.OrchestraSection.html...
Generating doc/ch8/sunmin/item56/JavaDocTest.Suspect.html...
Generating doc/ch8/sunmin/item56/package-summary.html...
Generating doc/ch8/sunmin/item56/package-tree.html...
Generating doc/constant-values.html...
Building index for all the packages and classes...
Generating doc/overview-tree.html...
Generating doc/index-all.html...
Building index for all classes...
Generating doc/allclasses-index.html...
Generating doc/allpackages-index.html...
Generating doc/deprecated-list.html...
Building index for all classes...
Generating doc/allclasses.html...
Generating doc/allclasses.html...
Generating doc/index.html...
Generating doc/help-doc.html...