[7주차] 이후성_item 56

8장_메서드/아이템 56 공개된 API 요소에는 항상 문서화 주석을 작성하라.md

@@ -0,0 +1,105 @@
+결론: 공개된 API라면 자바독 유틸리티를 활용하여 철저하게 문서화하라.
+-------------------------
+
+
+자바독: 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해주는 유틸리티.
+
+
+
+주요 자바독 태그로는 자바 5의 @literal, @code, 자바 8의 @implSpec, 자바 9의 @index가 있다.
+
+
+
+API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
+
+*문서화 주석: /** */
+```java
+    /**
+    * 이 클래스는 자바 문서화 주석의 예시를 보여줍니다.
+    * 이 클래스에 대한 자세한 설명을 여기에 작성할 수 있습니다.
+    *
+    * @author 홍길동
+    * @version 1.0
+      */
+      public class Example {
+
+    /**
+    * 주어진 정수의 제곱을 계산하여 반환합니다.
+    *
+    * @param number 제곱을 계산할 정수
+    * @return number의 제곱값
+      */
+      public int square(int number) {
+          return number * number;
+          }
+      }
+```
+
+*주의점: (자동으로 생성되는) 기본 생성자에는 문서화 주석을 달 수 없으니, 공개 클래스에서는 절대 기본 생성자를 사용하면 안된다.
+
+
+
+메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다. HOW가 아닌 WHAT을 작성해야 한다. 전제조건(precondition, @throws), 사후조건(postcondition), 부작용을 문서화 해야 한다.
+
+-----------------------------------------------------
+
+자바독 유틸리티는 문서화 주석을 HTML로 변환하므로 문서화 주석 안의 HTML 요소들이 최종 문서에 반영된다.
+
+
+
+일반적인 문서화 주석: 해당 메서드와 클라이언트 사이의 계약을 설명함.
+
+`@implSpec`: 해당 메서드와 하위 클래스 사이의 계약을 설명함.
+
+
+
+`{@code}`: 태그로 감싼 내용을 코드용 폰트로 렌더링한다. 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다.
+
+`{@literal}`: HTML 마크업이나 자바독 태그를 무시한다. 코드 폰트로 렌더링하진 않는다.
+
+-------------------------------------------------
+
+한 클래스(혹은 인터페이스) 안에서 요약 설명이 똑같은 멤버(혹은 생성자)가 둘 이상이면 안 된다.
+
+메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 동사구여야 한다.
+
+클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이어야 한다.
+
+
+
+제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
+```java
+    /**
+    * @param <K> the type of keys maintained by this map
+    * @param <V> the type of mapped values
+    *
+    * @author  Josh Bloch
+    * @since 1.2
+  */
+  public interface Map<K, V> {
+  // Query Operations
+```
+
+열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
+
+애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.
+
+패키지를 설명하는 문서화 주석은 `package-info.java` 파일에 작성한다.
+
+모듈 관련 설명은 `module.info.java` 파일에 작성한다.
+
+
+
+클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.
+
+------------------------------------------------------
+
+자바독은 메서드 주석을 상속시킬 수 있지만 사용하기 까다롭고 제약도 조금 있다.
+
+
+
+문서화 주석 외에도 전체 아키텍처를 설명하는 별도의 설명이 필요할 때가 있고, 이런 설명 문서가 있다면 문서화 주석에서 문서의 링크를 제공하라.
+
+
+
+정말 잘 쓰인 문서인지 확인하는 유일한 방법은 자바독 유틸리티가 생성한 웹페이지를 읽어보는 길 뿐이다.