A Few Tips on JavaDoc

posted in Uncategorized on by

JavaDoc에 대한 몇 가지 팁

It’s another Java 5-ish post which might not attract people, yet is very important. I find a lot of wrong or out-of-date JavaDoc due to lack of understandings on useful JavaDoc tags. Bad JavaDoc affects the quality of in-house softwares seriously, so knowing and using the following tips will improve the quality of your projects significantly.

사람들한테 별로 흥미가 없을, 하지만 아주 중요한 또 하나의 Java 5 스러운 이야기입니다. JavaDoc 태그에 대한 이해 부족으로 잘못되거나 철지난 내용을 담고 있는 JavaDoc을 많이 보아 왔습니다. 잘못된 JavaDoc은 사내 소프트웨어의 품질에 심각한 영향을 주므로, 다음의 팁을 이해하고 사용한다면 여러분 프로젝트의 질을 놀랍게 향상시킬 것입니다.

@link and @linkplain tags

@link tag creates a link to an other type. I always prefer to use @link tag rather than not using it because it’s robust to refactoring (i.e. renaming classes also changes JavaDoc). @linkplain is also useful when you prefer a text link with a variable width font.

@link 태그는 다른 타임으로의 링크를 만듭니다. 저는 항상 @link 태그를 쓰지 않는 것 보다는 쓰는 것을 선호하는데요, 리팩터링할 때 JavaDoc에 적어 놓은 클래스 이름이 깨지지 않아서입니다. @linkplain 또한 고정폭 텍스트 링크보다는 가변폭 텍스트 링크를 쓰고 싶을 때 유용합니다.

/**

 * Creates a new {@link Element} with the

 * specified name.

 */

package.html (or package-info.html)

javadoc detects an HTML file named as ‘package-info.html‘ in each package directory, and integrates its content into the generated JavaDoc. Here’s my template.

javadoc은 각 패키지 디렉토리의 ‘package-info.html‘ HTML 파일을 찾아 생성될 JavaDoc 내용에 통합시킵니다. 다음은 제가 쓰는 템플릿입니다.

<!DOCTYPE HTML PUBLIC

          "-//W3C//DTD HTML 3.2 Final//EN">

<html>

<head>

</head>

<body>

The first sentence is copied to the top of the

class list in the generated JavaDoc.  From here,

it's displayed after the generated class list.

...

</body>

</html>

package-info.java (New in Java 5)

Since Java 5, you can put package-info.java instead of package-info.html. What is the advantage BTW? It’s in that you can specify package annotation.

Java 5부터는 package-info.html 대신 package-info.java를 넣을 수 있습니다. 그런데 장점이 뭘까요? 장점은 패키지 애노테이션을 적어 줄 수 있다는 데 있습니다.

/**

 * The first sentence is copied to the top of the

 * class list in the generated JavaDoc.  From

 * here, it's displayed after the generated class

 * list.

 */

@Annotation1

@Annotation2 

...

package org.apache.mina.common;

That’s all. No class definition. It’s a bad idea to define a class here.

이게 답니다. 클래스 정의는 없습니다. 여기에 클래스를 정의하는 것은 좋지 않습니다.

@literal tag (New in Java 5)

No more unreadable &lt;s and &gt;s!

더이상 읽기 어려운 &lt;와 &gt;를 쓸 필요가 없습니다!

/**

 * Returns true when

 * {@literal the specified value < 3}.

 */

@code tag (New in Java 5)

@code tag is actually @literal + (<pre> or <code>).

@code 태그는 사실 @literal + (<pre> 또는 <code>) 입니다.

/**

 * Returns {@code true} when something cool

 * happened.  

 * {@code

 * multilined expression

 * is also fine.

 * }

 */

NOTE: JavaDoc doesn’t support multilined expression yet: Sun Bug Database.

NOTE: 아직 JavaDoc이 여러 줄로 나눠 쓰는 것을 지원하지 않네요: Sun Bug Database.

@value tag (Better in Java 5)

@value tag inlines the value of the specified static constant field.

@value 태그는 주어진 static 상수 필드의 값을 문서에 복사해 넣어 줍니다.

/**

 * Sets the property X.  If an invalid value is

 * specified, it's set to the default value,

 * {@value Constants#DEFAULT_X}).

 */

@deprecated tag and @Deprecated annotation

According to JavaDoc manual, it is a good practice to specify both a @deprecated tag (to specify a reason) and a @Deprecated annotation (for a compiler), though I don’t know why they had to introduce the annotation part.

JavaDoc 매뉴얼에 따르면 @deprecated 태그 (이유를 설명하기 위해)와 @Deprecated 애노테이션 (컴파일러를 위해)을 둘 다 쓰는 것이 좋다고 합니다. 왜 애노테이션을 만들어야 했었는지는 잘 모르겠지만요.

/**

 * @deprecated This method has been deprecated

 *             since 1.0 because it performs a

 *             unsafe operation that breaks data

 *             integrity.

 */

@Deprecated

2 Comments → A Few Tips on JavaDoc

Comments are closed.