Przykład kodu wielu linii w komentarzu Javadoc


531

Mam mały przykład kodu, który chcę uwzględnić w komentarzu Javadoc dla metody.

/**
 * -- 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
 */

Problem polega na tym, że przykład kodu pojawia się w Javadoc bez przerw w linii, co utrudnia czytanie.

-- 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 

Chyba się mylę, zakładając, że znacznik kodu poradzi sobie z łamaniem linii. Jaki jest najlepszy sposób formatowania przykładów kodu w komentarzach Javadoc?

Odpowiedzi:


743

Oprócz wspomnianych już <pre>znaczników, powinieneś również użyć @codeadnotacji JavaDoc, która znacznie ułatwi życie, jeśli chodzi o problemy z jednostkami HTML (w szczególności z Generics), np .:

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

Daje poprawny wynik HTML:

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

Pominięcie @codebloku (lub użycie <code>tagu) spowoduje HTML w następujący sposób:

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

(W celach informacyjnych opisy znaczników Java SE 8 można znaleźć tutaj: Tagi Javadoc )


63
Tak też bym pomyślał, ale niestety tak nie jest, musisz dodać tag <pre>, aby uzyskać podział linii.
Fabian Steeg

12
Niestety wydaje się, że gdy naciśniesz ctrl + shift + F (Formatuj kod w Eclipse), Eclipse przesuwa znacznik {@code} i zastępuje go kodem {& # 064; kod ...
jpdaigle

3
@jpdaigle Właśnie próbowałem tego w Eclipse Galileo i Helios, a formatyzator nic dla mnie nie zastępuje (w systemie Mac OS, ale nigdy nie widziałem, aby formater robił coś takiego na innych platformach).
Fabian Steeg

30
Kolejny niefortunny przypadek, jeśli w przykładowym kodzie znajdują się bloki używające nawiasów klamrowych „{}”, pierwszy nawias zamykający zakończy blok @code. Jednym sposobem jest użycie (poczekaj na to ...) elementów html dla nawiasów klamrowych. Nie widzę przekonującego argumentu dla tagów <pre> dla kodu z blokami.
Ed Griebel,

2
Zaćmienie miesza znacznik {@code} i zastępuje go kodem {& # 064; To nie jest z powodu Eclipse, to z powodu (błędnego?) Narzędzia javadoc. Jeśli masz znak @ w kodzie multilinii wewnątrz {@code ... multiline ...}, wówczas javadoc nie może poprawnie go przeanalizować :( Tak przynajmniej widzę implementację javadoc Oracle JDK1.7.0_45.
Mężczyzna

167

Miałem naprawdę ciężki czas z umieszczeniem konkretnego przykładu kodu w komentarzu javadoc. Chciałbym się tym podzielić.
Uwaga:

  • użycie old <code>- tag, aby zapobiec interpretacji nawiasów klamrowych
  • użycie {@code ...}tagu „new”, aby uzyskać ogólne dane wyjściowe
  • ucieczka znaku @ @Overrideza pomocą „ {@literal @}Override”, ponieważ generator javadoc „przechyla się” tam, ponieważ @ idzie bezpośrednio po nawiasach otwierających
  • usuń jedną przestrzeń przed {@codei {@literal, aby skompensować wewnętrzne przestrzenie i zachować wyrównanie

kod 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
  */

zostanie wydrukowany jako

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

2
To działa, ale pojawia się ostrzeżenie, gdy uruchamiam javadoc wysyłający to ostrzeżenie „Ostrzeżenie: {@code} w <code>”
Shane Rowatt

3
To zadziałało, zaakceptowana odpowiedź nie działa dobrze w moim zaćmieniu (4.6.2).
Eric Wang

Zastanawiam się, dlaczego to wszystko jest konieczne, mój intellij 13 i później działają dobrze z kodem w zaakceptowanej odpowiedzi. Czy to tylko problem zaćmienia?
bvdb

Tak, widziałem również, że działa dobrze w IntelliJ 11 i nowszych. IntelliJ obsługuje to poprawnie. Niestety Eclipse NIE renderuje poprawnie JavaDoc (stan najechania kursorem) i ignoruje zarówno nowe linie, jak i przerwy HTML. Próbuję znaleźć rozwiązanie, które działa dobrze w obu IDE, ponieważ są to dwa z najlepszych obecnie używanych IDE.
Michael M

41

Źródło Java ma na to wiele dobrych przykładów. Oto przykład z nagłówka „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>
...

9
Podsumowując,<pre><blockquote>...</blockquote></pre>
Jin Kwon

6
Raczej<p><blockquote><pre> </pre></blockquote></p>
masterxilo

@ JinKwon niestety to nie zawsze działa, nie w moim fragmencie kodu :( dodanie {@kodu na początku działa, nawet jeśli zamknięcie} nie zostanie osiągnięte
benez

Wydaje się, że działa to w przypadku większości kodów, ale nie uchodzi nawiasom kwadratowym, takim jak in List<String>. Do tego używam <pre>{@code ... }</pre>.
Daniel


14

Potrzebne są <pre></pre>tagi do podziału linii, a {@code ... }wewnątrz - dla ogólnych. Ale wtedy nie wolno umieszczać otwierającego nawiasu w tym samym wierszu co <generic>znacznik, ponieważ wtedy wszystko będzie ponownie wyświetlane w 1 wierszu.

Wyświetla w jednym wierszu:

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

Wyświetla z podziałami linii:

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

Kolejną dziwną rzeczą jest to, że po wklejeniu klamry zamykającej {@codepojawia się:

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

Wynik:

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

4
Witamy w przepełnieniu stosu. Aby sformatować kod w postach, możesz albo go poprzedzić (w osobnym akapicie) czterema spacjami, albo otoczyć je backtickami (`` ...``). Nie trzeba <code>i <pre>znaczniki. Zredagowałem twoją odpowiedź w tym umyśle.
Paŭlo Ebermann

10
/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/
  • <pre/> jest wymagany do zachowania linii.
  • {@code musi mieć własną linię
  • <blockquote/> jest tylko dla wcięcia.
public Foo(final Class<?> klass) {
    super();
    this.klass = klass;
}


AKTUALIZACJA z JDK8

Minimalne wymagania dla odpowiednich kodów to <pre/>i {@code}.

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

daje

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

Opcjonalne otoczenie <blockquote/>wstawia wcięcie.

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

daje

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

Wstawienie <p>lub otoczenie <p>i </p>daje ostrzeżenia.


5

Byłem w stanie wygenerować dobrze wyglądające pliki HTML za pomocą następującego fragmentu kodu pokazanego w Kodzie 1.

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

(Kod 1)

Kod 1 zamienił się w wygenerowaną stronę HTML javadoc na ryc. 1, zgodnie z oczekiwaniami.

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

(Ryc. 1)

Jednak w NetBeans 7.2, jeśli naciśniesz Alt + Shift + F (aby ponownie sformatować bieżący plik), kod 1 zmienia się w kod 2.

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

(Kod 2)

gdzie pierwsza <pre>jest teraz podzielona na dwie linie. Kod 2 generuje wygenerowany plik HTML javadoc, jak pokazano na ryc. 2.

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

(Ryc. 2)

Sugestia Steve'a B (Kod 3) wydaje się dawać najlepsze wyniki i pozostaje sformatowana zgodnie z oczekiwaniami, nawet po wciśnięciu Alt + Shift + F.

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

(Kod 3)

Użycie kodu 3 daje takie same dane wyjściowe HTML javadoc, jak pokazano na ryc. 1.


4

Oto moje dwa centy.

Jak już wskazują inne odpowiedzi, powinieneś używać <pre> </pre>w połączeniu z {@code }.

Użyj prei{@code}

  • Zawijanie kodu wewnątrz <pre>i </pre>zapobiega zwijaniu się kodu w jednym wierszu;
  • Zawijania kodu wewnątrz {@code }zapobiega <, >i wszystko pomiędzy od znikają. Jest to szczególnie przydatne, gdy kod zawiera wyrażenia ogólne lub lambda.

Problemy z adnotacjami

Problemy mogą pojawić się, gdy blok kodu zawiera adnotację. Jest tak prawdopodobnie dlatego, że gdy @znak pojawia się na początku linii Javadoc, jest uważany za znacznik Javadoc, taki jak @paramlub @return. Na przykład ten kod może zostać niepoprawnie przeanalizowany:

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

Powyższy kod całkowicie zniknie w moim przypadku.

Aby to naprawić, linia nie może zaczynać się od @znaku:

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

Zauważ, że pomiędzy @codei są dwie spacje @Override, aby zachować wyrównanie do następnych linii. W moim przypadku (przy użyciu Apache Netbeans) jest renderowany poprawnie.


3

Istnieje znacząca różnica między <blockquote><pre>...i <pre>{@code....Pierwsza z nich pominie deklaracje typu w generycznych, ale druga zachowa ją.

E.g.: List<MyClass> myObject = null; wyświetla się jak w List myObject = null;przypadku pierwszego i List<MyClass> myObject = null;drugiego


2

Jeśli jesteś programistą Androida, możesz użyć:

<pre class=”prettyprint”>

TODO:your code.

</pre>

Aby całkiem wydrukować kod w Javadoc z kodem Java.


1
Wyjaśnij: co w narzędziach Androida powinno działać, biorąc pod uwagę problemy wymagające tagu @code? A który składnik powinien definiować klasę prettyprint? Android używa zwykłego Javadoc.
noamtm

Xamarin / VS, Android Studio, czy to nie ma znaczenia?
tyblu

@tyblu Android Studio działa, ale Xamarin Studio / VS może nie działać. Możesz spróbować.
ifeegoo

1

Spróbuj zamienić „kod” na „pre”. Wstępny znacznik w HTML oznacza tekst jako wstępnie sformatowany, a wszystkie linie i spacje będą wyświetlane dokładnie podczas ich wpisywania.


1

Właśnie przeczytałem tutaj odniesienie do Javadoc 1.5 i tylko kod z <i >musi być zawarty w środku {@code ...}. Oto prosty przykład:

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

0

Mój przykładowy kod załączam do <pre class="brush: java"></pre>tagów i używam SyntaxHighlighter do opublikowanych javadocs. Nie szkodzi to IDE i sprawia, że ​​opublikowane przykłady kodu są piękne.



Za pomocą podświetlacza składni musisz załadować skrypt i poprawić css. Wygląda niesamowicie, ale musisz podać poprawną ścieżkę do wymaganych skryptów i css. Ponadto, jeśli chcesz korzystać z trybu offline, musisz uważać na prawidłowe ścieżki.
Alex Byrth,

0

Przy użyciu Java SE 1.6 wygląda na to, że wszystkie identyfikatory UPPERCASE PRE są najlepszym sposobem na zrobienie tego w Javadoc:

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

jest najprostszym sposobem na zrobienie tego.

Przykład z javadoc otrzymałem z metody java.awt.Event:

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

Daje to wynik, który wygląda dokładnie jak zwykły kod, z nienaruszonymi regularnymi odstępami kodów i nowymi wierszami.


2
To nie dodaje niczego do istniejących odpowiedzi.
madth3

madth3, masz rację. Wydawało mi się, że widziałem różnicę, gdy używam modyfikatorów wstępnych niższych niż WIELKIE, ale przy drugim spojrzeniu to nie wygląda tak. Może to również mieć związek z tym, jak wyglądał na tej stronie, a jak z javadoc.
Eugene_CD-adaptco

1
rozróżnia wielkie i małe litery w tagu html?
Jasonw,

0

Przynajmniej w programie Visual Studio Code możesz zmusić komentarz Javadoc do respektowania podziałów linii, zawijając go w potrójne odwrotne wstawki, jak pokazano poniżej:

/** ```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.
 ``` */
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.