Melhore a escrita das documentações Java com Asciidoclet
Grande notícia para os desenvolvedores Java que prezam por uma documentação clara e eficaz! Abel Salgado Romero, através de seu Twitter, anunciou o retorno do Asciidoclet, um plugin que permite escrever JavaDocs usando o formato AsciiDoc implementado em Java através do Asciidoctor. A nova versão, Asciidoclet 2.0.0, agora oferece suporte para Java 11, 17 e 21, eliminando a necessidade de misturar HTML nas documentações.
O Asciidoclet moderniza a escrita e leitura dos JavaDocs, tornando-os mais fáceis de entender e com mais recursos do que o HTML tradicional. Para funcionar, ele usa recursos internos do Java, necessitando de configurações específicas que dependem da versão do Java utilizada.
Como usar o Asciidoclet
Para os usuários do Maven, o Asciidoclet pode ser integrado através do maven-javadoc-plugin. É crucial prestar atenção nas opções additionalJOptions para configurar o acesso aos internos do Java necessários. Abaixo, segue um exemplo de configuração para Java 11:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.6.3</version>
<configuration>
<source>11</source>
<doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
<docletArtifact>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoclet</artifactId>
<version>{asciidoclet-version}</version>
</docletArtifact>
<overview>src/main/java/overview.adoc</overview>
<additionalparam>
--base-dir ${project.basedir}
--attribute "name=${project.name}"
--attribute "version=${project.version}"
--attribute "title-link=https://example.com[${project.name} ${project.version}]"
</additionalparam>
<additionalJOptions>
<additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
<additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
</additionalJOptions>
</configuration>
</plugin>Para o Gradle, o processo é similar, mas as opções do javadoc devem omitir o "-" inicial. Aqui está um exemplo para o uso com Java 17+:
plugins {
id 'java'
}
configurations {
asciidoclet
}
dependencies {
asciidoclet 'org.asciidoctor:asciidoclet:{asciidoclet-version}'
}
javadoc {
options {
docletpath = configurations.asciidoclet.files.asType(List)
doclet = 'org.asciidoctor.asciidoclet.Asciidoclet'
overview = "src/main/java/overview.adoc"
addStringOption "-base-dir", "${projectDir}"
addStringOption \
"-attribute",
"name=${project.name}," +
"version=${project.version}," +
"title-link=https://example.com[${project.name} ${project.version}]"
jFlags \
"--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED",
"--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED",
"--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED",
"--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED",
"--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED",
"--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED"
}
}Documentação oficial
As documentações detalhadas estarão disponíveis em breve no site oficial do Asciidoctor. Até lá, os interessados podem consultar o repositório do GitHub para obter mais informações e exemplos de uso.
Comentário pessoal
Neste blog, desenvolvido em Java, utilizo o formato AsciiDoc para criar os posts, empregando a biblioteca Asciidoctor para converter esses textos em HTML. Essa abordagem otimiza significativamente a gestão do conteúdo, proporcionando um fluxo de trabalho eficiente e integrado.
Conclusão
O plugin do Asciidoclet facilita a criação de documentações, bem como as torna mais acessíveis e fáceis de entender. É um grande passo para melhorar a eficiência e a qualidade da documentação de código, permitindo que os desenvolvedores se concentrem mais na lógica e menos na formatação. Acompanhe as atualizações e prepare-se para transformar a maneira como você documenta seus projetos Java com Asciidoclet!
