Comment documenter des API expérimentales ou incomplètes comme @deprecated?

12

Existe-t-il un bon terme similaire mais différent de «obsolète» pour signifier qu'une méthode ou une API est dans la base de code mais ne doit pas être utilisée car son implémentation n'est pas complète ou va probablement changer? (Ouais, je sais, ces méthodes ne devraient pas être publiques, yada yada yada. Je n'ai pas créé ma situation, j'essaie juste d'en tirer le meilleur parti.)

Que suggèrent les gens? Expérimental, incomplet, autre chose?

Si je construis de la documentation javadoc pour cette API qui est toujours en flux, dois-je utiliser la balise @deprecated ou existe-t-il une meilleure convention? Pour moi, @deprecated implique que cette API est ancienne et qu'un nouveau mécanisme préféré est disponible. Dans ma situation, il n'y a pas d'alternative, mais certaines des méthodes de l'API ne sont pas terminées et ne doivent donc pas être utilisées. À ce stade, je ne peux pas les rendre privés, mais je voudrais mettre des avertissements clairs dans les documents.

documentation terminology api documentation-generation javadocs Michael Levy
la source
Une balise «instable» serait également utile. Le sens serait quelque chose de différent. "Cela est censé fonctionner correctement, mais nous pourrions apporter des modifications à l'avenir".
Borjab

Réponses:

8

Le terme approprié est probablement incubateur , c'est celui utilisé par Google et Apache:

  • incubateur-google-web-toolkit

    L'incubateur officiel de widgets et de bibliothèques pour Google Web Toolkit ...

  • Incubateur Apache

    ... la passerelle pour les projets open source destinés à devenir des projets à part entière d'Apache Software Foundation ...

Si vous regardez de plus près les projets mentionnés ci-dessus, vous remarquerez peut-être que les API "expérimentales" (par exemple dans GWT) ont tendance à avoir des noms de packages "dédiés", comme com.google.gwt.gen2. Ceci pour éviter de polluer les futures API "finalisées" destinées à une consommation publique permanente - car, vous savez,

"Les API publiques, comme les diamants, sont éternelles. Vous avez une chance de bien faire les choses, alors faites de votre mieux ..." (Joshua Bloch, Comment concevoir une bonne API et pourquoi elle est importante )

moucheron
la source
2
Je penchais vers "Expérimental" après avoir vu des API comme developer.chrome.com/extensions/experimental.html
Michael Levy
10

J'utiliserais @deprecatedpour des raisons purement pratiques.

Bien @deprecatedqu'il ne transmette pas la signification exacte que vous souhaitez, il présente un avantage significatif: le compilateur Java a un support intégré pour cela. La compilation avec -deprecationindicateur vous permet de trouver tous les endroits où vous remplacez une méthode obsolète, aidant vos utilisateurs à trouver très rapidement le code suspect. Vous pouvez utiliser la @deprecatedbalise Javadoc pour expliquer ce qui se passe réellement à quiconque souhaite lire votre documentation. C'est là que vous pouvez dire à l'utilisateur que l'API est expérimentale, doit être utilisée à ses propres risques, etc.

dasblinkenlight
la source
1
+1. Excellent point. Avoir un support intégré est essentiel pour de telles parties de l'API et encourage les utilisateurs à consulter la documentation pour comprendre pourquoi ces parties sont marquées comme dépréciées.
Arseni Mourzenko
2
Je me penchais vers quelque chose comme "* @deprecated Ceci est une API expérimentale et susceptible de changer" au minimum pour que l'IDE et les documents mettent en évidence la méthode, puis pour avoir une brève explication.
Michael Levy
N'oubliez pas que la dépréciation créera de nombreux avertissements. Ce n'est peut-être pas aussi mauvais qu'il n'y paraît. Être averti des fonctionnalités expérimentales pourrait être acceptable.
Borjab
3

Je n'ai jamais rien vu de tel dans d'autres API, car les fonctionnalités expérimentales ou incomplètes n'ont rien à voir avec une API publique.

Puisque vous n'avez pas le choix, mettez simplement un avertissement clairement visible que la partie de l'API est susceptible de changer.

Arseni Mourzenko
la source
Bien. Par exemple, nous avons: junit.org/apidocs/org/junit/experimental/package-summary.html Soit dit en passant, l'utilisation du package était une idée géniale. Une fois que l'API est instable, vous devez modifier le package afin de rompre toutes les dépendances. Une annotation java aurait été bien meilleure
Borjab