Wie dokumentiere ich experimentelle oder unvollständige APIs wie @deprecated?

12

Gibt es einen guten Begriff, der ähnlich, aber anders als "veraltet" ist, um zu bedeuten, dass sich eine Methode oder API in der Codebasis befindet, aber nicht verwendet werden sollte, weil ihre Implementierung nicht vollständig ist oder sich wahrscheinlich ändern wird? (Ja, ich weiß, diese Methoden sollten nicht öffentlich sein, yada yada yada. Ich habe meine Situation nicht geschaffen, ich versuche nur, das Beste daraus zu machen.)

Was schlagen die Leute vor? Experimentell, unvollständig, noch etwas?

Soll ich das @deprecated-Tag verwenden, wenn ich eine Javadoc-Dokumentation für diese API erstelle, die noch im Fluss ist, oder gibt es eine bessere Konvention? Für mich bedeutet @deprecated, dass diese API alt ist und ein neuer bevorzugter Mechanismus verfügbar ist. In meiner Situation gibt es keine Alternative, aber einige der Methoden in der API sind noch nicht abgeschlossen und sollten daher nicht verwendet werden. Zum jetzigen Zeitpunkt kann ich sie nicht als privat kennzeichnen, aber ich möchte klare Warnungen in die Dokumente einfügen.

documentation terminology api documentation-generation javadocs Michael Levy
quelle
Ein "Unstable" -Tag wäre ebenfalls hilfreich. Die Bedeutung wäre etwas anderes. Msgstr "Das soll funktionieren, aber wir könnten in Zukunft einige Änderungen vornehmen".
Borjab

Antworten:

8

Geeigneter Begriff ist höchstwahrscheinlich Inkubator , dieser wird von Google und Apache verwendet:

  • Google-Web-Toolkit-Inkubator

    Der offizielle Inkubator von Widgets und Bibliotheken für Google Web Toolkit ...

  • Apache Inkubator

    ... das Tor für Open Source-Projekte, die zu vollwertigen Apache Software Foundation-Projekten werden sollen ...

Wenn Sie sich die oben genannten Projekte genauer ansehen, stellen Sie möglicherweise fest, dass "experimentelle" APIs (z. B. in GWT) tendenziell "dedizierte" Paketnamen haben, z com.google.gwt.gen2. Damit soll vermieden werden, dass zukünftige "finalisierte" APIs, die für den dauerhaften öffentlichen Konsum bestimmt sind, verschmutzt werden.

"Öffentliche APIs wie Diamanten sind für immer. Sie haben eine Chance, es richtig zu machen, also geben Sie Ihr Bestes ..." (Joshua Bloch, Wie man eine gute API entwirft und warum es wichtig ist )

Mücke
quelle
2
Ich neigte zu "Experimental", nachdem ich APIs wie developer.chrome.com/extensions/experimental.html
Michael Levy
10

Ich würde @deprecatedaus rein praktischen Gründen verwenden.

Obwohl @deprecatedes nicht die genaue Bedeutung vermittelt, die Sie möchten, hat es einen signifikanten Vorteil: Der Java-Compiler hat eine eingebaute Unterstützung dafür. Durch das Kompilieren mit -deprecationflag können Sie alle Stellen finden, an denen Sie eine veraltete Methode überschreiben. So können Ihre Benutzer verdächtigen Code sehr schnell finden. Mit dem @deprecatedJavadoc-Tag können Sie jedem erklären, was wirklich vor sich geht, der Ihre Dokumentation lesen möchte. Hier können Sie dem Benutzer mitteilen, dass die API experimentell ist, auf eigenes Risiko verwendet werden sollte und so weiter.

dasblinkenlight
quelle
1
+1. Hervorragender Punkt. Ein integrierter Support ist für solche Teile der API von wesentlicher Bedeutung und fordert die Benutzer auf, die Dokumentation zu lesen, um zu verstehen, warum diese Teile als abgeschrieben gekennzeichnet sind.
Arseni Mourzenko
2
Ich neigte zu etwas wie "* @deprecated Dies ist eine experimentelle API und wird sich wahrscheinlich zumindest ändern", damit die IDE und die Dokumentation die Methode hervorheben und dann eine kurze Erklärung haben.
Michael Levy
Denken Sie nur daran, dass veraltete eine Menge Warnungen erstellen. Das ist vielleicht nicht so schlimm, wie es scheint. Es kann in Ordnung sein, vor experimentellen Funktionen gewarnt zu werden.
Borjab,
3

Ich habe so etwas noch nie in anderen APIs gesehen, da experimentelle oder unvollständige Funktionen in einer öffentlichen API nichts zu tun haben.

Da Sie keine Wahl haben, machen Sie einfach eine deutlich sichtbare Warnung, dass sich der Teil der API ändern kann.

Arseni Mourzenko
quelle
Gut. Zum Beispiel haben wir: junit.org/apidocs/org/junit/experimental/package-summary.html Die Verwendung des Pakets war übrigens eine schreckliche Idee. Sobald die API instabil ist, müssen Sie das Paket ändern, damit alle Abhängigkeiten verletzt werden. Eine Java-Anmerkung wäre viel besser gewesen
Borjab