Verwaltung von Javadoc-Tags '@since'

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 Benutzervorgabenseite 'Konsole' öffnen Plug-in-Entwicklung > API-Fehler/-Warnungen geändert werden.

Fehlende '@since'-Tags

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.

Fehlerhafte '@since'-Tags

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:

Ungültige '@since'-Tag-Versionen

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:

Zugehörige Tasks
Referenzkonfiguration einrichten

Zugehörige Referenzinformationen
Benutzervorgaben API-Referenzkonfiguration
Benutzervorgaben API-Fehler und Warnungen