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?
Miałem naprawdę ciężki czas z umieszczeniem konkretnego przykładu kodu w komentarzu javadoc. Chciałbym się tym podzielić.
Uwaga:
<code>
- tag, aby zapobiec interpretacji nawiasów klamrowych{@code ...}
tagu „new”, aby uzyskać ogólne dane wyjściowe@Override
za pomocą „{@literal @}Override
”, ponieważ generator javadoc „przechyla się” tam, ponieważ @ idzie bezpośrednio po nawiasach otwierających{@code
i{@literal
, aby skompensować wewnętrzne przestrzenie i zachować wyrównaniekod javadoc:
zostanie wydrukowany jako
źródło
Źródło Java ma na to wiele dobrych przykładów. Oto przykład z nagłówka „String.java”:
źródło
<pre><blockquote>...</blockquote></pre>
<p><blockquote><pre>
</pre></blockquote></p>
List<String>
. Do tego używam<pre>{@code ... }</pre>
.Dołącz swój kod wielowierszowy
<pre></pre>
tagami.źródło
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:
Wyświetla z podziałami linii:
Kolejną dziwną rzeczą jest to, że po wklejeniu klamry zamykającej
{@code
pojawia się:Wynik:
źródło
...
``). Nie trzeba<code>
i<pre>
znaczniki. Zredagowałem twoją odpowiedź w tym umyśle.<pre/>
jest wymagany do zachowania linii.{@code
musi mieć własną linię<blockquote/>
jest tylko dla wcięcia.AKTUALIZACJA z JDK8
Minimalne wymagania dla odpowiednich kodów to
<pre/>
i{@code}
.daje
Opcjonalne otoczenie
<blockquote/>
wstawia wcięcie.daje
Wstawienie
<p>
lub otoczenie<p>
i</p>
daje ostrzeżenia.źródło
Byłem w stanie wygenerować dobrze wyglądające pliki HTML za pomocą następującego fragmentu kodu pokazanego w Kodzie 1.
(Kod 1)
Kod 1 zamienił się w wygenerowaną stronę HTML javadoc na ryc. 1, zgodnie z oczekiwaniami.
(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.
(Kod 2)
gdzie pierwsza
<pre>
jest teraz podzielona na dwie linie. Kod 2 generuje wygenerowany plik HTML javadoc, jak pokazano na ryc. 2.(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.
(Kod 3)
Użycie kodu 3 daje takie same dane wyjściowe HTML javadoc, jak pokazano na ryc. 1.
źródło
Oto moje dwa centy.
Jak już wskazują inne odpowiedzi, powinieneś używać
<pre>
</pre>
w połączeniu z{@code
}
.Użyj
pre
i{@code}
<pre>
i</pre>
zapobiega zwijaniu się kodu w jednym wierszu;{@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@param
lub@return
. Na przykład ten kod może zostać niepoprawnie przeanalizowany:Powyższy kod całkowicie zniknie w moim przypadku.
Aby to naprawić, linia nie może zaczynać się od
@
znaku:Zauważ, że pomiędzy
@code
i są dwie spacje@Override
, aby zachować wyrównanie do następnych linii. W moim przypadku (przy użyciu Apache Netbeans) jest renderowany poprawnie.źródło
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 wList myObject = null;
przypadku pierwszego iList<MyClass> myObject = null;
drugiegoźródło
Jeśli jesteś programistą Androida, możesz użyć:
Aby całkiem wydrukować kod w Javadoc z kodem Java.
źródło
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.
źródło
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:źródło
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.źródło
Przy użyciu Java SE 1.6 wygląda na to, że wszystkie identyfikatory UPPERCASE PRE są najlepszym sposobem na zrobienie tego w Javadoc:
jest najprostszym sposobem na zrobienie tego.
Przykład z javadoc otrzymałem z metody java.awt.Event:
Daje to wynik, który wygląda dokładnie jak zwykły kod, z nienaruszonymi regularnymi odstępami kodów i nowymi wierszami.
źródło
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:
źródło