Zarządzanie znacznikami @since dokumentacji Javadoc

Narzędzia interfejsu API udostępniają obsługę zarządzania znacznikami @since dokumentacji Javadoc w nowych elementach dodanych do interfejsu API (typach, metodach, polach itp.). Nowym elementem interfejsu API może być nowy typ dodany do pakietu interfejsu API, nowy typ dodany to typu interfejsu API, nowa metoda dodana do typu interfejsu API lub nowe pole dodane do typu interfejsu API. Dodanie metody to przypadek szczególny, przy czym może ono oznaczać dodanie metody do typu, nadpisanie metody klasy macierzystej, implementacja metody interfejsu nadrzędnego lub zmiana sygnatury istniejących metod.

Uwaga: Informacje o znaczniku @since nie są propagowane przez implementację lub tworzenie klas pochodnych. Każdy z elementów dodanych do interfejsu API powinien mieć własny znacznik @since oraz informację o wersji.

Narzędzia udostępniają następujące typy sprawdzania poprawności znaczników @since:

Preferencje dotyczące zarządzania znacznikami @since można zmieniać na stronie preferencji Otworzenie strony preferencji konsoli Programowanie wtyczek > Błędy i ostrzeżenia interfejsu API.

Brakujące znaczniki @since

Każdy wykryty nowy element interfejsu API zostanie sprawdzony przez narzędzia, aby upewnić się, że ma znacznik @since. Jeśli nowy element nie ma znacznika @since, zostanie oznaczony jako wymagający znacznika. Zostanie również zaproponowana wersja znacznika. Zaproponowana wersja nowego znacznika będzie bieżącą wersją pakunku - z wyjątkiem przypadku wprowadzenia w interfejsie API zmiany powodującej niezgodność, kiedy aktualizacji wymaga także wersja pakunku. Jeśli wersja pakunku także będzie wymagać aktualizacji, to zaproponowana wersja brakującego znacznika @since będzie wersją proponowanej wersji pakunku.

Należy przeanalizować następujący przykład: istnieje pakunek A w wersji 1.0.0 oraz klasa C, która została dodana w wersji 1.1.0 pakunku A zawierającego metodę m1().

Zniekształcone znaczniki @since

W nowych elementach może zostać sprawdzona spójność znaczników @since w celu zapewnienia, że zostały poprawnie utworzone. Narzędzia API sprawdzają, czy wszystkie znaczniki @since spełniają ogólne wymogi dotyczące formatu:

[@since] [wstęp] [dwuczęściowa wersja] [informacje końcowe]

Poniżej przedstawiono przykłady znacznika @since:

Niepoprawne wersje znacznika @since

Znaczniki @since nowych elementów mogą również zostać sprawdzone pod kątem ważności. Znacznik @since jest uważany za poprawny, jeśli informacja o wersji w znaczniku jest zgodna z wersją pakunku.

Poniżej przedstawiono przykład, w którym dodano nową metodę m2() do klasy interfejsu API w pakunku A w wersji 1.0.0:

Czynności pokrewne
Konfigurowanie wersji bazowej

Informacje pokrewne
Preferencje wersji bazowych interfejsu API
Preferencje błędów i ostrzeżeń interfejsu API