Javadoc 주석의 여러 줄 코드 예제

메소드에 대한 Javadoc 주석에 포함하려는 작은 코드 예제가 있습니다.

/**
 * -- ex: looping through List of Map objects --
 * <code>
 * for (int i = 0; i < list.size(); i++) {
 *      Map map = (Map)list.get(i);
 *      System.out.println(map.get("wordID"));
 *      System.out.println(map.get("word"));
 * }
 * </code>
 * 
 * @param query - select statement
 * @return List of Map objects
 */

문제는 코드 예제가 줄 바꿈없이 Javadoc에 표시되어 읽기가 어렵다는 것입니다.

-- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get("wordID")); System.out.println(map.get("word")); } 
Parameters
query - - select statement 
Returns:
List of Map objects 

코드 태그가 줄 바꿈을 처리한다고 가정하면 잘못되었다고 생각합니다. Javadoc 주석에서 코드 예제를 형식화하는 가장 좋은 방법은 무엇입니까?

이미 언급 된 <pre>태그 외에도@code JavaDoc 주석을 이렇게하면 HTML 엔터티 문제 (특히 제네릭의 경우)와 관련하여 훨씬 쉽게 사용할 수 있습니다.

* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>

올바른 HTML 출력을 제공합니다.

Set<String> s;
System.out.println(s);

@code블록을 생략 하거나 <code>태그를 사용 하면 다음과 같은 HTML이 생성됩니다.

Set s;
System.out.println(s);

(참고로 Java SE 8 태그 설명은 여기에서 찾을 수 있습니다 : Javadoc 태그 )

javadoc 주석에 특정 코드 예제를 포함시키는 데 정말 힘든 시간을 보냈습니다. 이것을 공유하고 싶습니다.
다음 사항에 유의하십시오.

• <code>중괄호가 해석되지 않도록하는 오래된 태그 사용법
• "new"사용법 {@code ...}-출력에 포함 된 제네릭을 얻기위한 태그
• javadoc 생성기가 "기울기"하기 때문에 @ @Override" 를 통해 @ 기호를 이스케이프 처리{@literal @}Override
• 앞의 하나의 공간을 제거 {@code하고 {@literal, 내부 공간을 보상하기 위해 그리고 정렬을 유지

javadoc 코드 :

/** this methods adds a specific translator from one type to another type. `
  * i.e.
  * <pre>
  * <code>new BeanTranslator.Builder()
  *   .translate(
  *     new{@code Translator<String, Integer>}(String.class, Integer.class){
  *      {@literal @}Override
  *       public Integer translate(String instance) {
  *         return Integer.valueOf(instance);
  *       }})
  *   .build();
  * </code>
  * </pre>
  * @param translator
  */

로 인쇄됩니다

new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

Java 소스에는 이에 대한 좋은 예가 많이 있습니다. 다음은 "String.java"헤드의 예입니다.

....
 * is equivalent to:
 * <p><blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <p><blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
...

여러 줄 코드를 <pre></pre>태그 로 묶습니다 .

<pre></pre>줄 바꿈 에는 태그 가 필요하고 {@code ... }제네릭 에는 태그 가 필요합니다 . 그러나 여는 괄호를 같은 줄에 배치 할 수 없습니다<generic> 태그 모든 항목이 다시 한 줄에 표시되기 때문입니다.

한 줄에 표시됩니다.

* ..
* <pre>
* {@code
* public List<Object> getObjects() {
*    return objects;
* }
* </pre>
* ..

줄 바꿈이있는 디스플레이 :

* ..
* <pre>
* {@code
* public List<Object> getObjects() 
* {
*    return objects;
* }
* </pre>
* ..

또 다른 이상한 점은의 닫는 중괄호를 붙여 넣으면 {@code표시됩니다.

* ..
* <pre>
* {@code
*   public List<Object> getObjects() 
*   {
*     return objects;
*   }
* }
* </pre>
* ..

산출:

public List<Object> getObjects() 
{
   return objects;
}
}

/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/

• <pre/> 선을 보존하는 데 필요합니다.
• {@code 자체 라인이 있어야합니다
• <blockquote/> 들여 쓰기 전용입니다.

public Foo(final Class<?> klass) {
    super();
    this.klass = klass;
}

적절한 코드의 최소 요구 사항은 <pre/>및 {@code}입니다.

/**
 * test.
 *
 * <pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre>
 */

수확량

 <T> void test(Class<? super T> type) {
     System.out.printf("hello, world\n");
 }

그리고 선택적인 주변 환경 <blockquote/>은 들여 쓰기를 삽입합니다.

/**
 * test.
 *
 * <blockquote><pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre></blockquote>
 */

수확량

     <T> void test(Class<? super T> type) {
         System.out.printf("hello, world\n");
     }

삽입 <p>또는 둘러싼 <p>및 </p>수율 경고.

코드 1에 표시된 다음 코드 조각으로 멋진 HTML 파일을 생성 할 수있었습니다.

 * <pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 *</pre>

(코드 1)

코드 1은 예상대로 그림 1에서 생성 된 javadoc HTML 페이지로 바뀌었다.

A-->B
 \
  C-->D
   \   \
    G   E-->F

(그림 1)

그러나 NetBeans 7.2에서 Alt + Shift + F (현재 파일을 다시 포맷하기 위해)를 누르면 코드 1이 코드 2로 바뀝니다.

 * <
 * pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 * </pre>

(코드 2)

첫 번째 줄 <pre>은 이제 두 줄로 나뉩니다. 코드 2는 그림 2와 같이 생성 된 javadoc HTML 파일을 생성합니다.

< pre> A-->B \ C-->D \ \ G E-->F

(그림 2)

Steve B의 제안 (코드 3)은 최상의 결과를 제공하는 것으로 보이며 Alt + Shift + F를 누른 후에도 예상대로 형식을 유지합니다.

*<p><blockquote><pre>         
* A-->B
*  \
*   C-->D
*    \   \
*     G   E-->F
* </pre></blockquote>

(코드 3)

코드 3을 사용하면 그림 1과 같은 javadoc HTML 출력이 생성됩니다.

여기 내 센트가 있습니다.

다른 답변에서 이미 언급했듯이 <pre> </pre>와 함께 사용해야합니다 {@code }.

사용 pre및{@code}

• 내부 코드를 포장 <pre>하고 </pre>한 줄에 붕괴 코드를 방지;
• 코드를 안에 {@code }넣으면 <, >그리고 그 사이의 모든 것이 사라지지 않습니다. 이것은 코드에 제네릭 또는 람다식이 포함 된 경우 특히 유용합니다.

주석 관련 문제

코드 블록에 주석이 포함 된 경우 문제가 발생할 수 있습니다. 때 때문 아마 @기호는 자바 독 라인의 시작 부분에 나타납니다, 그것은 같은 자바 독 태그 고려 @param나 @return. 예를 들어,이 코드는 잘못 구문 분석 될 수 있습니다.

/**
 * Example usage:
 *
 * <pre>{@code
 * @Override
 * public void someOverriddenMethod() {

위의 코드는 필자의 경우 완전히 사라집니다.

이 문제를 해결하려면 줄을 @부호로 시작해서는 안됩니다 .

/**
 * Example usage:
 *
 * <pre>{@code  @Override
 * public int someMethod() {
 *     return 13 + 37;
 * }
 * }</pre>
 */

@code와 사이에 두 줄의 공백 @Override이있어 다음 줄과 일을 정렬합니다. 필자의 경우 (Apache Netbeans 사용) 올바르게 렌더링됩니다.

<blockquote><pre>...와 사이에 큰 차이가 있습니다<pre>{@code.... 전자는 제네릭에서 형식 선언을 생략하지만 후자는 유지합니다.

E.g.: List<MyClass> myObject = null;List myObject = null;firts와 마찬가지로 List<MyClass> myObject = null;두 번째 와 같이 표시

Android 개발자 인 경우 다음을 사용할 수 있습니다.

<pre class=”prettyprint”>

TODO:your code.

</pre>

Java 코드로 Javadoc에서 코드를 인쇄하려면

"code"를 "pre"로 바꾸십시오. HTML의 사전 태그는 텍스트를 사전 형식으로 표시하며 모든 줄 바꿈과 공백은 입력 한대로 정확하게 나타납니다.

난 그냥 자바 독 1.5 참조 읽어 여기 에, 오직 코드 <와 >내부를 묶어야합니다 {@code ...}. 간단한 예를 들면 다음과 같습니다.

 /** 
 * Bla bla bla, for example:
 *
 * <pre>
 * void X() {
 *    List{@code <String>} a = ...;
 *    ...
 * }
 * </pre>
 *
 * @param ...
 * @return ...
 */
 .... your code then goes here ...

예제 코드를 <pre class="brush: java"></pre>태그로 묶고 게시 된 javadoc에 SyntaxHighlighter 를 사용 합니다. IDE를 손상시키지 않으며 게시 된 코드 예제를 아름답게 만듭니다.

Java SE 1.6을 사용하면 모든 UPPERCASE PRE 식별자가 Javadoc에서이를 수행하는 가장 좋은 방법 인 것 같습니다.

/**
 * <PRE>
 * insert code as you would anywhere else
 * </PRE>
 */

가장 간단한 방법입니다.

java.awt.Event 메소드에서 얻은 javadoc의 예 :

/**
 * <PRE>
 *    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
 *    int offmask = CTRL_DOWN_MASK;
 *    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
 *        ...
 *    }
 * </PRE>
 */

이렇게하면 일반 코드 간격과 줄 바꿈이 그대로있는 일반 코드와 똑같은 출력이 생성됩니다.

적어도 Visual Studio Code에서는 아래 표시된 것처럼 Javadoc 주석이 줄 바꿈을 삼중 선으로 감싸서 강제로 적용하도록 할 수 있습니다.

/** ```markdown
 * This content is rendered in (partial) markdown.
 * 
 * For example, *italic* and **bold** text works, but [links](https://www.google.com) do not.
 * Bonus: it keeps single line-breaks, as seen between this line and the previous.
 ``` */