Como documentar APIs experimentais ou incompletas, como @ obsoleto?

12

Existe um bom termo semelhante, mas diferente de "descontinuar", para significar que um método ou API está na base de código, mas não deve ser usado porque sua implementação não está completa ou provavelmente será alterada? (Sim, eu sei, esses métodos não devem ser públicos, yada yada yada. Eu não criei minha situação, estou apenas tentando fazer o melhor possível.)

O que as pessoas sugerem? Experimental, Incompleto, outra coisa?

Se estou criando documentação javadoc para essa API que ainda está em fluxo, devo usar a tag @deprecated ou existe uma convenção melhor? Para mim, o termo deprecado implica que essa API é antiga e que um novo mecanismo preferido está disponível. Na minha situação, não há alternativa, mas alguns dos métodos na API não estão concluídos e, portanto, não devem ser usados. Neste momento, não posso torná-los privados, mas gostaria de colocar avisos claros nos documentos.

documentation terminology api documentation-generation javadocs Michael Levy
fonte
Uma tag "Instável" também seria útil. O significado seria algo diferente. "Isso deve funcionar bem, mas podemos fazer algumas alterações no futuro".
Borjab

Respostas:

8

O termo apropriado é provavelmente incubadora , usado pelo Google e Apache:

Se você olhar mais de perto os projetos mencionados acima, poderá observar que as APIs "experimentais" (por exemplo, no GWT) tendem a ter nomes de pacotes "dedicados", como com.google.gwt.gen2. Isso evita poluir a futura API "finalizada" destinada ao consumo público permanente - porque, você sabe,

"APIs públicas, como diamantes, são para sempre. Você tem uma chance de acertar, então dê o melhor de si ..." (Joshua Bloch, Como criar uma boa API e por que é importante )

mosquito
fonte
2
Eu estava inclinado para o "Experimental" depois de ver APIs como developer.chrome.com/extensions/experimental.html
Michael Levy
10

Eu usaria @deprecatedpor razões puramente práticas.

Embora @deprecatednão transmita o significado exato que você deseja, ele possui uma vantagem significativa: o compilador Java possui suporte interno para ele. Compilar com -deprecationsinalizador permite encontrar todos os lugares em que você substitui um método obsoleto, ajudando seus usuários a encontrar códigos suspeitos muito rapidamente. Você pode usar a @deprecatedtag Javadoc para explicar o que realmente está acontecendo com qualquer pessoa que queira ler sua documentação. É aqui que você pode dizer ao usuário que a API é experimental, deve ser usada por seu próprio risco e assim por diante.

dasblinkenlight
fonte
1
+1. Ponto excelente. Ter um suporte interno é essencial para essas partes da API e incentiva os usuários a ver a documentação para entender por que essas partes estão marcadas como depreciadas.
Arseni Mourzenko 15/10/12
2
Eu estava inclinado a algo como "* @ reprovado Esta é uma API experimental e provavelmente mudará" no mínimo para que o IDE e os documentos destacem o método e, em seguida, tenham uma breve explicação.
Michael Levy
Apenas lembre-se de que descontinuado criará muitos avisos. Isso pode não ser tão ruim quanto parece. Ser avisado sobre recursos experimentais pode ser bom.
Borjab
3

Nunca vi algo assim em outras APIs, pois os recursos experimentais ou incompletos não têm nada a ver em uma API pública.

Como você não tem opções, basta colocar um aviso claramente visível de que a parte da API está sujeita a alterações.

Arseni Mourzenko
fonte
Bem. Por exemplo, temos: junit.org/apidocs/org/junit/experimental/package-summary.html A propósito, usar o pacote foi uma ideia terrível. Quando a API estiver instável, você precisará alterar o pacote para violar todas as dependências. Uma anotação java teria sido muito melhor
Borjab