Gerenciamento de Tags Javadoc @since

As Ferramentas da API fornecem suporte para o gerenciamento de tags Javadoc @since em elementos novos que foram incluídos na API (tipos, métodos, campos, etc.). Novos elementos da API poderiam representar um novo tipo incluído em um pacote de API, um novo tipo incluído em um tipo de API, um novo método incluído em um tipo de API ou um novo campo incluído em um tipo de API. A inclusão de método é um caso especial, em que uma inclusão de método poderia ser incluir um método em um tipo, substituir um método da classe pai, implementar um método de interface pai ou alterar a assinatura de um método existente.

Nota: Informações da tag @since não são propagadas por meio da implementação ou da definição como subclasse. Cada elemento que é incluído na API deve ter sua própria tag @since e informações de versão.

O conjunto de ferramentas fornece a seguinte validação para as tags @since:

As preferências para o gerenciamento de tags @since podem ser alteradas na página de preferências Abre a página de preferências Console Desenvolvimento de Plug-in > Erros/Avisos da API.

Tags @since ausentes

Todo novo elemento da API detectado será verificado pelo conjunto de ferramentas para garantir que ele tenha uma tag @since. Se o novo elemento não tiver uma tag @since, ele será sinalizado como precisando ter uma, e uma versão da tag será proposta. A versão proposta para a nova tag será a versão atual do pacote configurável - exceto no caso de uma alteração de quebra de API, em que a versão do pacote configurável também precisa ser atualizada. Se a versão do pacote configurável também precisar ser atualizada, a versão proposta para a tag @since ausente será aquela da versão proposta do pacote configurável.

Considere o seguinte exemplo: termos um pacote configurável A com a versão 1.0.0 e temos uma classe C que foi incluída na versão 1.1.0 de A que contém o método m1().

Tags @since malformadas

Novos elementos podem ter suas tags @since verificadas em relação à consistência para garantir que foram formuladas corretamente. As ferramentas da API verificam se todas as tags @since seguem o formato geral de:

[@since] [pre-amble] [2 part version] [post-amble]

Considere os seguintes exemplos de tag @since:

Versões de tag @since inválidas

Novos elementos podem ter também suas tags @since verificadas em relação à validade. Uma tag @since é considerada válida se as informações de versão na tag corresponderem à versão do pacote configurável.

Considere o seguinte exemplo, em que incluímos um novo método m2() a uma classe de API no pacote configurável A, cuja versão é 1.0.0:

Tarefas relacionadas
Configurando uma Linha de Base

Referência relacionada
Preferências de Linhas de Base API
Preferências de Avisos e Erros de API