Java Language => Java 코드 문서화

소개

자바 코드에 대한 문서는 종종 javadoc을 사용하여 생성됩니다. Javadoc은 java 소스 코드에서 HTML 형식의 API 문서 를 생성 하기 위해 Sun Microsystems에서 만들었습니다. HTML 형식을 사용하면 관련 문서를 함께 하이퍼 링크 할 수있는 편리함을 제공합니다.

통사론

/ ** - 클래스, 필드, 메소드 또는 패키지에서 JavaDoc 시작
@author // 클래스, 인터페이스 또는 enum의 작성자 이름을 지정합니다. 필수 항목입니다.
@version // 해당 클래스, 인터페이스 또는 enum의 버전. 필수 항목입니다. 소스 제어 소프트웨어가 체크 아웃 할 때 % I % 또는 % G %와 같은 매크로를 사용할 수 있습니다.
@param // 메소드 또는 생성자의 인수 (매개 변수)를 표시합니다. 각 매개 변수에 대해 @param 태그를 하나 지정하십시오.
@return // void가 아닌 메소드의 반환 유형을 표시합니다.
@exception // 메소드 나 생성자에서 어떤 예외가 발생할 수 있는지 보여줍니다. 반드시 잡히게되는 예외는 여기에 나열되어야합니다. 원하는 경우 ArrayIndexOutOfBoundsException과 같이 catch 할 필요가없는 요소도 포함 할 수 있습니다. Throw 할 수있는 각 예외에 대해 하나의 @exception을 지정하십시오.
@throws // @exception과 동일합니다.
@see // 메소드, 필드, 클래스 또는 패키지에 링크합니다. package.Class # something의 형태로 사용하십시오.
@since //이 메소드, 필드 또는 클래스가 추가되었을 때. 예를 들어, java.util.Optional <T> 와 같은 클래스의 JDK-8.
@serial, @serialField, @serialData // serialVersionUID를 표시하는 데 사용됩니다.
@deprecated // 클래스, 메소드 또는 필드를 사용되지 않는 것으로 표시합니다. 예를 들어, 하나는 java.io.StringBufferInputStream 입니다. 더 이상 사용되지 않는 기존 클래스의 전체 목록을 보려면 여기를 클릭하십시오 .
{@link} // @see와 비슷하지만 사용자 정의 텍스트와 함께 사용할 수 있습니다. 자세한 내용은 JFrame # setDefaultCloseOperation을 참조하십시오. {@link #setDefaultCloseOperation (int closeOperation))
{@linkplain} // 코드 글꼴이 없어도 {@link}과 유사합니다.
{@code} // HTML 태그와 같은 문자 코드. 예 : {@code <html> </ html>}. 그러나이 글꼴은 고정 폭 글꼴을 사용합니다. 모노 스페이스 글꼴없이 동일한 결과를 얻으려면 {@literal}을 사용하십시오.
{@literal} // 고정 폭 글꼴이 아닌 {@code}와 동일합니다.
{@value} // 정적 필드의 값을 표시합니다. JFrame # EXIT_ON_CLOSE 값은 {@value}입니다. 또는 특정 필드에 연결할 수 있습니다. 앱 이름 {@value AppConstants # APP_NAME}을 사용합니다.
{@docRoot} // 현재 파일에 상대적인 JavaDoc HTML의 루트 폴더. 예 : <a href="{@docRoot}/credits.html"> 크레딧 </a>.
HTML은 허용됩니다 : <code> "Hi cookies".substring (3) </ code>.
* / - JavaDoc 선언의 끝

비고

Javadoc은 코드 주석을 HTML 문서로 변환 할 수있는 JDK에 포함 된 도구입니다. Java API 스펙 은 Javadoc을 사용하여 생성되었습니다. 타사 라이브러리에 대한 많은 문서에서도 마찬가지입니다.

클래스 문서

모든 Javadoc 주석은 블록 주석으로 시작하고 별표 ( /** )와 블록 주석 ( */ )이 끝나면 끝납니다. 선택적으로, 각 줄은 임의의 공백과 하나의 별표로 시작할 수 있습니다. 이것들은 문서 파일이 생성 될 때 무시됩니다.

/**
 * Brief summary of this class, ending with a period.
 *
 * It is common to leave a blank line between the summary and further details.
 * The summary (everything before the first period) is used in the class or package 
 * overview section.
 *
 * The following inline tags can be used (not an exhaustive list): 
 * {@link some.other.class.Documentation} for linking to other docs or symbols
 * {@link some.other.class.Documentation Some Display Name} the link's appearance can be 
 * customized by adding a display name after the doc or symbol locator
 * {@code code goes here} for formatting as code
 * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup 
 * or other tags.
 *
 * Optionally, the following tags may be used at the end of class documentation 
 * (not an exhaustive list):
 *
 * @author John Doe
 * @version 1.0
 * @since 5/10/15
 * @see some.other.class.Documentation
 * @deprecated This class has been replaced by some.other.package.BetterFileReader
 * 
 * You can also have custom tags for displaying additional information.
 * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
 * command line option, you can create a custom tag.
 *
 * Example custom tag and generation:
 * @custom.updated 2.0    
 * Javadoc flag: -tag custom.updated:a:"Updated in version:"
 * The above flag will display the value of @custom.updated under "Updated in version:"
 *
 */
public class FileReader {
}

Classes 사용 된 것과 동일한 태그 및 형식을 Enums 및 Interfaces 에도 사용할 수 있습니다.

방법 문서

/**
 * Brief summary of method, ending with a period.
 *
 * Further description of method and what it does, including as much detail as is 
 * appropriate.  Inline tags such as
 * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
 *
 * If a method overrides a superclass method, {@inheritDoc} can be used to copy the 
 * documentation
 * from the superclass method
 *
 * @param stream Describe this parameter.  Include as much detail as is appropriate
 *               Parameter docs are commonly aligned as here, but this is optional.
 *               As with other docs, the documentation before the first period is 
 *               used as a summary.
 *
 * @return Describe the return values.  Include as much detail as is appropriate
 *         Return type docs are commonly aligned as here, but this is optional.
 *         As with other docs, the documentation before the first period is used as a 
 *         summary.
 *
 * @throws IOException Describe when and why this exception can be thrown.
 *                     Exception docs are commonly aligned as here, but this is 
 *                     optional.
 *                     As with other docs, the documentation before the first period 
 *                     is used as a summary.
 *                     Instead of @throws, @exception can also be used.
 *
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated  Describe why this method is outdated. A replacement can also be specified.
 */
public String[] read(InputStream stream) throws IOException {
    return null;
}

필드 문서

/**
 * Fields can be documented as well.
 * 
 * As with other javadocs, the documentation before the first period is used as a
 * summary, and is usually separated from the rest of the documentation by a blank 
 * line.
 * 
 * Documentation for fields can use inline tags, such as:
 * {@code code here}
 * {@literal text here}
 * {@link other.docs.Here}
 * 
 * Field documentation can also make use of the following tags:
 * 
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated Describe why this field is outdated
 */
public static final String CONSTANT_STRING = "foo";

패키지 문서

Java SE 5

Javadoc에서 package-info.java 라는 파일을 사용하여 패키지 수준의 문서를 작성할 수 있습니다. 이 파일의 형식은 다음과 같습니다. 선행 공백과 별표 (선택 사항), 일반적으로 형식을 지정하기 위해 각 행에 표시

/**
 * Package documentation goes here; any documentation before the first period will 
 * be used as a summary.
 *
 * It is common practice to leave a blank line between the summary and the rest
 * of the documentation; use this space to describe the package in as much detail
 * as is appropriate.
 * 
 * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
 * and {@literal text here} can be used in this documentation.
 */
package com.example.foo;

// The rest of the file must be empty.

위의 경우이 파일 package-info.java Java 패키지 com.example.foo 의 폴더에 넣어야합니다.

모래밭

다른 Javadocs와의 연결은 @link 태그로 수행됩니다.

/**
 * You can link to the javadoc of an already imported class using {@link ClassName}.
 *
 * You can also use the fully-qualified name, if the class is not already imported: 
 *  {@link some.other.ClassName}
 *
 * You can link to members (fields or methods) of a class like so:
 *  {@link ClassName#someMethod()}
 *  {@link ClassName#someMethodWithParameters(int, String)}
 *  {@link ClassName#someField}
 *  {@link #someMethodInThisClass()} - used to link to members in the current class
 *  
 * You can add a label to a linked javadoc like so:
 *  {@link ClassName#someMethod() link text} 
 */

@see 태그를 사용하면 See also 섹션 에도 요소를 추가 할 수 있습니다. @param 나 @return 와 같이, 표시되는 장소는 관련이 없습니다. 스펙에서는 @return 뒤에 써야한다고 말합니다.

/**
 * This method has a nice explanation but you might found further
 * information at the bottom.
 *
 * @see ClassName#someMethod()
 */

외부 리소스 에 대한 링크 를 추가하려면 HTML <a> 태그를 사용하면됩니다. 어디서나 또는 @link 및 @see 태그 내부에서 인라인으로 사용할 수 있습니다.

/**
 * Wondering how this works? You might want
 * to check this <a href="http://stackoverflow.com/">great service</a>.
 *
 * @see <a href="http://stackoverflow.com/">Stack Overflow</a>
 */

명령 행에서 Javadocs 빌드하기

많은 IDE가 자동으로 Javadocs에서 HTML을 생성 할 수 있도록 지원합니다. 일부 빌드 도구 (예 : Maven 및 Gradle )에는 HTML 작성을 처리 할 수있는 플러그인이 있습니다.

그러나 이러한 도구는 Javadoc HTML을 생성 할 필요가 없습니다. 이 작업은 명령 줄 javadoc 도구를 사용하여 수행 할 수 있습니다.

이 도구의 가장 기본적인 사용법은 다음과 같습니다.

javadoc JavaFile.java

JavaFile.java 의 Javadoc 주석에서 HTML을 생성합니다.

[source-directory] 있는 모든 java 파일을 재귀 적으로 읽는 명령 줄 도구를 실제로 사용하면 [package.name] 및 모든 하위 [package.name] 대한 설명서가 만들어지고 [docs-directory] :

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]

인라인 코드 문서

Javadoc 문서 외에도 코드는 인라인으로 문서화 할 수 있습니다.

단일 행 주석은 // 의해 시작되며 같은 행에 있지만 이전에는없는 명령문 뒤에 위치 할 수 있습니다.

public void method() {
  
  //single line comment
  someMethodCall(); //single line comment after statement
  
}

여러 줄 주석은 /* 와 */ 사이에 정의됩니다. 그것들은 여러 줄에 걸쳐있을 수 있으며 명령문 사이에 위치 할 수도 있습니다.

public void method(Object object) {
  
  /*
    multi 
    line 
    comment
  */
  object/*inner-line-comment*/.method(); 
}

JavaDocs는 /** 시작하는 특수 형식의 여러 줄 주석입니다.

너무 많은 인라인 주석은 코드의 가독성을 떨어 뜨릴 수 있으므로 코드가 충분히 설명되지 않거나 디자인 결정이 명확하지 않은 경우 드문 드문 사용되어야합니다.

한 줄 주석에 대한 추가 사용 사례는 컨벤션 기반 키워드 인 TAG를 사용하는 것입니다. 일부 개발 환경에서는 이러한 단일 주석에 대한 특정 규칙을 인식합니다. 일반적인 예는 다음과 같습니다.

//TODO
//FIXME

아니면 Jira에 대한 참조를 발행하십시오.

//PRJ-1234

문서 내의 코드 스 니펫

문서 내에 코드를 작성하는 표준 방법은 {@code } 구문을 사용하는 것입니다. <pre></pre> 안에 여러 줄의 코드 줄이있는 경우.

/**
 * The Class TestUtils.
 * <p>
 * This is an {@code inline("code example")}.
 * <p>
 * You should wrap it in pre tags when writing multiline code.
 * <pre>{@code
 *  Example example1 = new FirstLineExample();
 *  example1.butYouCanHaveMoreThanOneLine();
 * }</pre>
 * <p>
 * Thanks for reading.
 */
class TestUtils {

때로는 복잡한 코드를 javadoc 주석에 넣어야 할 수도 있습니다. @ 기호는 특별히 문제가 있습니다. {@literal } 구문과 함께 오래된 <code> 태그를 사용하면 문제가 해결됩니다.

/**
 * Usage:
 * <pre><code>
 * class SomethingTest {
 * {@literal @}Rule
 *  public SingleTestRule singleTestRule = new SingleTestRule("test1");
 *
 * {@literal @}Test
 *  public void test1() {
 *      // only this test will be executed
 *  }
 *
 *  ...
 * }
 * </code></pre>
 */
class SingleTestRule implements TestRule { }

Modified text is an extract of the original Stack Overflow Documentation

아래 라이선스 CC BY-SA 3.0

와 제휴하지 않음 Stack Overflow

Java Language
Java 코드 문서화

수색…

소개

통사론

비고