Javadoc 알고 쓰기

Java 수업때 가장 등한시했던 부분이 바로 Javadoc이었는데 이제 정말 필요한 상황이 왔다. 코드를 작성하는 시간보다 코드를 다시 보고, 다른사람에게 설명하는데 쓰는시간이 배로 많다. 잘 작성된 Javadoc은 이런 비효율적인 일을 줄여줄 수 있다.

 

기계인간 Johngrib님의 포스팅과 javadoc 문서를 참고했다.
예시 코드는 Android Source Code다.

 

작성 원칙

• 코드의 역할을 3초안에 파악할 수 있도록하는 것이 목적이다.
• 가독성이 중요하다.
• 세부 구현은 언제든지 바뀔 수 있으므로 구현에 대한 내용은 적지 않는다.
  • 루프를 돌아서 반환한다던가 하는 설명

 

@deprecated <설명>

/**
* Main Sidecar interface definition that will be used by the WindowManager library to get custom
* OEM-provided information that isn't covered by platform APIs.
* @deprecated Use androidx.window.extensions instead of this package.
*/

@Deprecated
public interface SidecarInterface {...}

이 API가 더이상 사용되지 않음을 알릴 때 사용한다. 따라서 대개 @Deprecated 어노테이션이 붙은 코드와 함께한다.

• 첫번째 문장은 언제 API가 Deprecated되었으며, 대신에 무엇을 사용해야하는지 설명해주어야한다.
• 따라오는 문장에는 왜 Deprecated 되었는지 설명해야한다.

 

@throws <클래스명> <설명>

/**
* Asserts that this collection of nodes is equal to the given [expectedSize].
* Provides a detailed error message on failure.
* @throws AssertionError if the size is not equal to [expectedSize]
*/
fun SemanticsNodeInteractionCollection.assertCountEquals(
    expectedSize: Int
)

@exception 태그와 동일하지만 @throws가 더 권장된다. 메소트 혹은 생성자에 붙을 수 있다.

• 어떤 종류의 Exception이 던져지는지 명시한다.
• 어떤 상황에 Expcetion이 던져지는지 이유를 적는다.

 

@param <타입-이름> <설명>

/**
 * Sets a {@link CaptureRequest.Key} and Value on the configuration.
 *
 * <p>The value will override any value set by CameraX internally with the risk of
 * interfering with some CameraX CameraControl APIs as well as 3A behavior.
 *
 * @param key      The {@link CaptureRequest.Key} which will be set.
 * @param value    The value for the key.
 * @param <ValueT> The type of the value.
 * @return The current Extender.
 */
@NonNull
public <ValueT> Extender<T> setCaptureRequestOption(
        @NonNull CaptureRequest.Key<ValueT> key, @NonNull ValueT value) {...}

파라미터에 대한 간략한 설명이다.

• 타입을 명시할때는 Angle Brackets(<>)를 사용한다.

 

@return <설명>

/**
 * Send [KeyEvent] to the content.
 * @return true if the event was consumed by the content
 */
fun sendKeyEvent(event: ComposeKeyEvent): Boolean = postponeInvalidation {
    return focusedOwner?.sendKeyEvent(event) == true
}

리턴값에 대해 설명한다.

• 리턴값의 반환 유형을 설명한다.
• 리턴값이 허용되는 범위의 값을 설명한다.
• Boolean을 리턴할 경우, 어떤 경우에 true이고 어떨 경우에 false인지 명시한다.
  • 종립님의 글을 읽으면서 매우 찔리면서도 공감했던 부분인데, "~인지 여부"라는 단어는 애매모호 하므로 피하는 것이 좋다.

 

@see <참고대상>

/**
* <i>Optional</i>: Default value is 0
*
* @see Carousel#setPaddingRes(int)
*/
public HorizontalCarouselModel_ paddingRes(@DimenRes int paddingRes) {
    ...
}

참고해야하는 대상을 가리킨다.

• 클래스의 메소드를 가리킬때는 Dog#bow() 처럼 #를 사용한다.
• 하이퍼 링크를 걸 수 있다. <a href="URL#value">label</a>