Tłumaczenie: Używanie składni Markdown w komentarzach Javadoc

Używanie składni Markdown w komentarzach Javadoc

W tym poście przyjrzymy się, jak pisać komentarze Javadoc przy użyciu języka Markdown zamiast standardowej składni Javadoc. Czym więc jest Markdown? Markdown to prosty język znaczników, który opcjonalnie można przetłumaczyć na HTML za pomocą narzędzia o tej samej nazwie. Markdown jest powszechnie używany do formatowania plików Readme, podczas pisania postów na forach oraz w edytorach tekstu do szybkiego tworzenia pięknych dokumentów tekstowych. (Wikipedia: Markdown ) Tekst sformatowany w Markdown jest bardzo łatwy do odczytania. Różne wersje Markdown są używane w Stack Overflow lub GitHub do formatowania treści generowanych przez użytkowników.

Instalacja

Domyślnie narzędzie Javadoc używa komentarzy Javadoc do generowania dokumentacji API w formacie HTML. Proces ten można ponownie skonfigurować za pomocą Doclets . Doclety to programy Java określające zawartość i format pliku wyjściowego narzędzia Javadoc. Markdown-doclet zastępuje standardowy dokument Java, dając programiście możliwość używania składni Markdown w komentarzach Javadoc. Możesz zainstalować go w Maven za pomocą wtyczki maven-javadoc. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Pisanie komentarzy w Markdown

Możesz teraz używać składni Markdown do pisania komentarzy Javadoc: /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } Po wykonaniu

mvn javadoc:Javadoc

wygenerowany dokument HTML API znajduje się pod adresem

cel/strona/apidocs.

Dokument wygenerowany dla powyższego kodu wygląda następująco: Jak widać na rysunku, komentarze Javadoc są doskonale konwertowane do formatu HTML.

Wniosek

Markdown ma wyraźną przewagę nad standardową składnią Javadoc: jest znacznie łatwiejszy do odczytania w kodzie źródłowym. Wystarczy spojrzeć na niektóre komentarze do metod w java.util.Map: wiele z nich jest pełnych znaczników formatujących i trudno je odczytać bez użycia dodatkowych narzędzi. Należy jednak pamiętać, że Markdown może powodować problemy z narzędziami i IDE, które działają tylko ze standardową składnią Javadoc. Źródło: Używanie składni Markdown w komentarzach Javadoc od naszego partnera JCG , Michaela Scharhaga, z bloga mscharhag, Programming and Stuff.