Die API-Tools bieten Unterstützung für die Verwaltung von Javadoc-Tags @since für neue
Elemente, die zur Anwendungsprogrammierschnittstelle (API) hinzugefügt wurden (Typen, Methoden, Felder usw.).
Neue API-Elemente könnten zum Beispiel ein neuer, zu einem API-Paket hinzugefügter Typ, ein neuer, zu einem API-Typ hinzugefügter Typ, eine neue, zu einem API-Typ hinzugefügte Methode oder ein neues, zu einem API-Typ hinzugefügtes Feld sein.
Das Hinzufügen von Methoden ist ein Sonderfall, bei dem das Hinzufügen einer Methode aus dem Hinzufügen einer Methode zu einem Typ, dem Außerkraftsetzen der Methode einer übergeordneten Klasse, dem Implementieren der Methode einer übergeordneten Schnittstelle oder dem Ändern der Signatur einer vorhandenen Methode bestehen könnte.
Hinweis: Die @since-Tag-Informationen werden nicht über Implementierung oder Unterklassenbildung weitergegeben. Von jedem Element, das zur API hinzugefügt wird, wird erwartet, dass es über seinen eigenen @since-Tag und seine eigenen Versionsinformationen verfügt.
Die Tools stellen die folgenden Prüfungen für @since-Tags bereit:
Die Benutzervorgaben für die Verwaltung von @since-Tags können auf der Benutzervorgabenseite
Plug-in-Entwicklung > API-Fehler/-Warnungen geändert werden.
Jedes neue API-Element, das erkannt wird, wird von den Tools geprüft, um sicherzustellen, dass es einen @since-Tag besitzt.
Hat das neue Element keinen @since-Tag, erhält es eine Markierung, die angibt, dass es einen solchen Tag benötigt, und es wird eine Version für den Tag vorgeschlagen.
Als Version für den neuen Tag wird die aktuelle Version des Produktpakets vorgeschlagen - außer in dem Fall einer Fehler verursachenden API-Änderung, die auch eine Aktualisierung der Produktpaketversion erforderlich machen würde. Wenn die Produktpaketversion ebenfalls aktualisiert werden muss, wird als Version für den fehlenden @since-Tag die Version vorgeschlagen, die auch für die Produktpaketversion vorgeschlagen wurde.
Nehmen Sie den folgenden Fall als Beispiel: Es ist ein Produktpaket A mit Version 1.0.0 vorhanden und eine Klasse 'C', die in Version 1.1.0 von A hinzugefügt wurde und die Methode 'm1()' enthält.
@since-Tag und schlagen vor, dass 'm2()' mit einem neuen Tag @since 1.1 versehen wird.@since-Tag und schlagen vor, dass 'm2()' einen neuen Tag @since 2.0 erhält. Hierbei ist 2.0.0 die neue vorgeschlagene Produktpaketversion.
Die @since-Tags neuer Elemente können auf ihre Konsistenz hin überprüft werden, um sicherzustellen, dass sie ordnungsgemäß formuliert sind. Die API-Tools prüfen, ob alle @since-Tags dem folgenden allgemeinen Format entsprechen:
[@since] [präambel] [2-teilige version] [postambel]
Betrachten Sie die folgenden @since-Tag-Beispiele:
@since A 1 added m2(): würde als fehlerhaft markiert, da im zweiten Segment die Version fehlt@since: würde als fehlerhaft markiert, da keine Versionsinformationen vorhanden sind@since A: würde markiert, da keine Versionsinformationen vorhanden sind@since 1.0.0: würde markiert, da die Version zu viele Segmente aufweist@since A 1.0 added m2(): würde nicht markiert
Bei neuen Elementen kann ebenfalls eine Überprüfung der Gültigkeit ihrer @since-Tags ausgeführt werden. Ein @since-Tag gilt als gültig, wenn die Informationen im Tag mit der Version des Produktpakets übereinstimmen.
Betrachten Sie das folgende Beispiel, in dem eine neue Methode 'm2()' zu einer API-Klasse im Produktpaket A hinzugefügt wurde, das die Version '1.0.0' hat:
@since A 1.0 added method m2(): gilt als gültig@since A 2.0 added method m2(): ist ungültig, da das Produktpaket A die Version 1.0.0 hat@since A 0.1 added method m2(): ist ungültig, da das Produktpaket A die Version 1.0.0 hat

Referenzkonfiguration einrichten

Benutzervorgaben API-Referenzkonfiguration
Benutzervorgaben API-Fehler und Warnungen