Tradução: Usando sintaxe Markdown em comentários Javadoc

Usando sintaxe Markdown em comentários Javadoc

Nesta postagem, veremos como você pode escrever comentários Javadoc usando Markdown em vez da sintaxe padrão do Javadoc. Então, o que é Markdown? Markdown é uma linguagem de marcação simples que pode opcionalmente ser traduzida para HTML usando a ferramenta de mesmo nome. Markdown é amplamente usado para formatar arquivos leia-me, ao escrever postagens em fóruns e em editores de texto para criar rapidamente belos documentos de texto. (Wikipedia: Markdown ) O texto formatado em Markdown é muito fácil de ler. Vários tipos de Markdown são usados ​​no Stack Overflow ou GitHub para formatar o conteúdo gerado pelo usuário.

Instalação

Por padrão, a ferramenta Javadoc usa comentários Javadoc para gerar documentação de API como HTML. Este processo pode ser reconfigurado usando Doclets . Doclets são programas Java que especificam o conteúdo e a formatação do arquivo de saída da ferramenta Javadoc. Markdown-doclet substitui o Java Doclet padrão e, portanto, dá ao desenvolvedor a capacidade de usar a sintaxe Markdown em seus comentários Javadoc. Você pode instalá-lo no Maven usando o plugin maven-javadoc. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Escrevendo comentários no Markdown

Agora você pode usar a sintaxe Markdown para escrever comentários 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) { ... } Após a execução

mvn javadoc: Javadoc

o documento HTML API gerado está localizado em

alvo/site/apidocs.

O documento gerado para o código acima é assim: Como você pode ver na figura, os comentários Javadoc são perfeitamente convertidos para HTML.

Conclusão

Markdown tem uma clara vantagem sobre a sintaxe padrão do Javadoc: é muito mais fácil de ler no código-fonte. Basta dar uma olhada em alguns dos comentários do método em java.util.Map: muitos deles estão cheios de tags de formatação e são difíceis de ler sem o uso de ferramentas adicionais. Mas você precisa lembrar que o Markdown pode causar problemas com ferramentas e IDEs que só funcionam com a sintaxe padrão do Javadoc. Fonte: Usando sintaxe Markdown em comentários Javadoc de nosso parceiro JCG Michael Scharhag do blog mscharhag, Programming and Stuff.