Traduzione: utilizzo della sintassi Markdown nei commenti Javadoc

Utilizzo della sintassi Markdown nei commenti Javadoc

In questo post vedremo come scrivere commenti Javadoc utilizzando Markdown anziché la sintassi Javadoc standard. Allora cos'è Markdown? Markdown è un semplice linguaggio di markup che può essere facoltativamente tradotto in HTML utilizzando lo strumento con lo stesso nome. Markdown è ampiamente utilizzato per formattare file leggimi, quando si scrivono post nei forum e negli editor di testo per creare rapidamente bellissimi documenti di testo. (Wikipedia: Markdown ) Il testo formattato in Markdown è molto facile da leggere. Vari tipi di Markdown vengono utilizzati su Stack Overflow o GitHub per formattare i contenuti generati dagli utenti.

Installazione

Per impostazione predefinita, lo strumento Javadoc utilizza i commenti Javadoc per generare la documentazione API in formato HTML. Questo processo può essere riconfigurato utilizzando Doclet . I doclet sono programmi Java che specificano il contenuto e la formattazione del file di output dello strumento Javadoc. Markdown-doclet sostituisce il Java Doclet standard e offre quindi allo sviluppatore la possibilità di utilizzare la sintassi Markdown nei commenti Javadoc. Puoi installarlo in Maven usando maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Scrivere commenti in Markdown

Ora puoi utilizzare la sintassi Markdown per scrivere commenti 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) { ... } dopo l'esecuzione

mvn javadoc:Javadoc

si trova il documento API HTML generato in

target/sito/apidocs.

Il documento generato per il codice precedente si presenta così: Come puoi vedere dalla figura, i commenti Javadoc vengono perfettamente convertiti in HTML.

Conclusione

Markdown ha un chiaro vantaggio rispetto alla sintassi Javadoc standard: è molto più facile da leggere nel codice sorgente. Basta dare un'occhiata ad alcuni commenti sui metodi in java.util.Map: molti di essi sono pieni di tag di formattazione e sono difficili da leggere senza utilizzare strumenti aggiuntivi. Ma devi ricordare che Markdown può causare problemi con strumenti e IDE che possono funzionare solo con la sintassi Javadoc standard. Fonte: utilizzo della sintassi Markdown nei commenti Javadoc del nostro partner JCG Michael Scharhag dal blog mscharhag, Programming and Stuff.