Pular para o conteúdo principal

Java aprimora a documentação com suporte Markdown

Permite que os comentários da documentação do JavaDoc sejam escritos em Markdown, em vez de apenas em uma mistura de HTML e JavaDoc @-tags.


JEP 467, Markdown Documentation Comments, foi promovido para ser liberado no JDK 23

Objetivos da JEP

Tornar os comentários da documentação da API mais fáceis de escrever e ler no formato de origem, introduzindo a capacidade de usar a sintaxe Markdown nos comentários da documentação, juntamente com elementos HTML e tags JavaDoc.


Estende a API Compiler Tree para permitir que outras ferramentas que analisam comentários de documentação manipulem o conteúdo Markdown nesses comentários.


Não é o objetivo desta JEP, permitir a conversão automatizada de comentários de documentação existentes para a sintaxe Markdown.


Motivação

Os comentários da documentação Java tradicionalmente usam tags HTML e JavaDoc, uma escolha prática em 1995, mas desde então se tornou menos conveniente. HTML é prolixo e difícil de escrever à mão, especialmente para desenvolvedores que talvez não estejam familiarizados com ele. Tags JavaDoc embutidas, como {@link} e {@code}, são complicadas e muitas vezes exigem documentação de referência para uso adequado.


Markdown, por outro lado, é uma linguagem de marcação leve e fácil de ler e escrever. Ele oferece suporte a estruturas de documentos simples, como parágrafos, listas, texto estilizado e links, tornando-o um substituto adequado para HTML em comentários de documentação. Além disso, o Markdown permite a inclusão de HTML para construções que não suportam diretamente, proporcionando flexibilidade e reduzindo a complexidade.


Como exemplo do uso de Markdown em um comentário de documentação, considere o comentário para java.lang.Object.hashCode:


/**
* Returns a hash code value for the object. This method is
* supported for the benefit of hash tables such as those provided by
* {@link java.util.HashMap}.
* <p>
* The general contract of {@code hashCode} is:
* <ul>
* <li>Whenever it is invoked on the same object more than once during
*     an execution of a Java application, the {@code hashCode} method
*     must consistently return the same integer, provided no information
*     used in {@code equals} comparisons on the object is modified.
*     This integer need not remain consistent from one execution of an
*     application to another execution of the same application.
* <li>If two objects are equal according to the {@link
*     #equals(Object) equals} method, then calling the {@code
*     hashCode} method on each of the two objects must produce the
*     same integer result.
* <li>It is <em>not</em> required that if two objects are unequal
*     according to the {@link #equals(Object) equals} method, then
*     calling the {@code hashCode} method on each of the two objects
*     must produce distinct integer results.  However, the programmer
*     should be aware that producing distinct integer results for
*     unequal objects may improve the performance of hash tables.
* </ul>
*
* @implSpec
* As far as is reasonably practical, the {@code hashCode} method defined
* by class {@code Object} returns distinct integers for distinct objects.
*
* @return  a hash code value for this object.
* @see     java.lang.Object#equals(java.lang.Object)
* @see     java.lang.System#identityHashCode
*/


Este comentário pode ser escrito em Markdown da seguinte forma:


/// Returns a hash code value for the object. This method is
/// supported for the benefit of hash tables such as those provided by
/// [java.util.HashMap].
///
/// The general contract of `hashCode` is:
///
///   - Whenever it is invoked on the same object more than once during
///     an execution of a Java application, the `hashCode` method
///     must consistently return the same integer, provided no information
///     used in `equals` comparisons on the object is modified.
///     This integer need not remain consistent from one execution of an
///     application to another execution of the same application.
///   - If two objects are equal according to the
///     [equals][#equals(Object)] method, then calling the
///     `hashCode` method on each of the two objects must produce the
///     same integer result.
///   - It is _not_ required that if two objects are unequal
///     according to the [equals][#equals(Object)] method, then
///     calling the `hashCode` method on each of the two objects
///     must produce distinct integer results.  However, the programmer
///     should be aware that producing distinct integer results for
///     unequal objects may improve the performance of hash tables.
///
/// @implSpec
/// As far as is reasonably practical, the `hashCode` method defined
/// by class `Object` returns distinct integers for distinct objects.
///
/// @return  a hash code value for this object.
/// @see     java.lang.Object#equals(java.lang.Object)
/// @see     java.lang.System#identityHashCode


Principais diferenças a serem observadas:


O uso de Markdown é indicado por uma nova forma de comentário de documentação em que cada linha começa com /// em vez da sintaxe tradicional /** ... */.


O elemento HTML <p> não é obrigatório; uma linha em branco indica uma quebra de parágrafo.


Os elementos HTML <ul> e <li> são substituídos por marcadores de lista com marcadores Markdown, usando - para indicar o início de cada item na lista.


O elemento HTML <em> é substituído por sublinhados (_) para indicar a alteração da fonte.


As instâncias da tag {@code ...} são substituídas por crases (`...`) para indicar a fonte monoespaçada.


Instâncias de {@link ...} para vincular a outros elementos do programa são substituídas por formas estendidas de links de referência Markdown.


Instâncias de tags de bloco, como @implSpec, @return e @see, geralmente não são afetadas, exceto que o conteúdo dessas tags agora também está em Markdown, por exemplo, aqui nos crases do conteúdo da tag @implSpec.


A imagem abaixo compara as duas versões:



Referências:


https://www.infoq.com/news/2024/05/jep467-markdown-in-javadoc/


https://openjdk.org/jeps/467








Comentários

Postagens mais visitadas deste blog

Java Records

  Java Records Imutável, Simples e limpa Esta funcionalidade da linguagem apareceu pela primeira vez na versão 14 como experimental e assim continuou até a versão 15 . Agora liberada de forma definitiva no Java 16 . O objetivo é ser possível ter classes que atuam como portadores transparentes de dados imutáveis. Os registros podem ser considerados tuplas nominais. Ou seja, após criado, um record não pode mais ser alterado. Records oferece uma uma sintaxe compacta para declarar classes que são portadores transparentes para dados imutáveis superficiais visando reduzir significamente o detalhamento dessas classes e irá melhorar a capacidade de leitura e manutenção do código. Vamos seguir um exemplo de uma classe chamada Pessoa . O primeiro exemplo vamos utilizar o modo tradicional. public class Pessoa { private String nome; private int idade; public Pessoa (String nome, int idade) { super (); this .nome = nome; this .idade = idade; } public String g...

O suporte de longo prazo e o que o LTS significa para o ecossistema Java

A arte do suporte de longo prazo e o que o LTS significa para o ecossistema Java Aqui está o que o Java 17 tem em comum com o Java 11 e o Java 8. Em junho de 2018, há pouco mais de três anos, a Oracle e outros participantes do ecossistema Java anunciaram uma mudança no modelo de cadência de lançamento para Java SE. Em vez de ter um lançamento principal planejado a cada dois ou quatro anos (que geralmente se torna de três a quatro anos), um novo modelo de lançamento de recursos de seis meses seria usado: a cada três anos, um lançamento seria designado como Long-Term Support (LTS) e receba apenas atualizações trimestrais de segurança, estabilidade e desempenho. Esse padrão foi emprestado descaradamente do modelo de lançamento do Mozilla Firefox, mas o ajustou para ficar mais alinhado com os requisitos de uma plataforma de desenvolvimento. A primeira versão do Java lançada sob esse modelo foi o Java SE 11. O lançamento do Java SE 17, o segundo lançamento do LTS sob o novo ...

Java 8 ao 18: Mudanças mais importantes na plataforma Java

    Vamos rever muitas das mudanças mais importantes na plataforma Java que aconteceram entre a versão 8 (2014) e 18 (2022)   O Java 8 foi lançado em março de 2014 e o Java 18 em março de 2022. São 8 anos de progresso, 203 JEPs (JDK Enhancement Proposals ), entre essas duas versões. Neste post, revisaremos as mudanças mais importantes e discutiremos os benefícios e desafios da adoção de versões mais recentes do JDK para novos aplicativos e para os mais antigos compilados com versões mais antigas. Desde a versão 9, o Java tem novos recursos a cada 6 meses e é muito difícil acompanhar essas novas mudanças. A maioria das informações na internet descreve as mudanças entre as duas últimas versões do Java. No entanto, se você estiver em uma situação semelhante à minha, não está usando uma das versões mais recentes do Java, mas uma das várias versões anteriores (Geralmente 8 ou 11 que são as versões de suporte estendido). Então é útil saber quais novos recursos foram...