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
Programowanie wtyczek > Błędy i ostrzeżenia
interfejsu API.
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().
@since w metodzie
m2() i zaproponują umieszczenie nowego znacznika @since 1.1 w
metodzie m2().@since w metodzie
m2() i zasugerują umieszczenie nowego znacznika @since 2.0 w
metodzie m2(). Wersja 2.0.0
to proponowana nowa wersja pakunku.
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:
@since A 1 dodano metodę m2(): zostanie oznaczony jako
zniekształcony ze względu na brak drugiego segmentu informacji o wersji@since: zostanie oznaczony jako zniekształcony ze względu na brak informacji o wersji@since A: zostanie oznaczony ze względu na brak informacji o wersji@since 1.0.0: zostanie oznaczony z powodu zbyt wielu segmentów dotyczących wersji@since A 1.0 dodano metodę m2(): nie zostanie oznaczony
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:
@since A 1.0 dodano metodę m2(): jest uważany za
poprawny@since A 2.0 dodano metodę m2(): jest niepoprawny,
ponieważ wersja pakunku A to 1.0.0@since A 0.1 dodano metodę m2(): jest niepoprawny,
ponieważ wersja pakunku A to 1.0.0

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