Správa značek Javadoc @since

Modul API Tools poskytuje podporu pro správu značek dokumentace Javadoc @since v nových prvcích, které byly přidány do rozhraní API (typy, metody, pole atd.). Nové prvky rozhraní API mohou být novým typem přidaným do balíku API, novým type přidaným do typu API, novou metodou přidanou do typu API nebo novým polem přidaným do typu API. Přidání metody je zvláštní případ, kdy přidání metody může být přidání určité metody do určitého typu, potlačení metody nadřízené třídy, implementace metody rozhraní nebo změna existující signatury metody.

Poznámka: Informace značky @since se nešíří prostřednictvím implementace ani vytvořením podtřídy. U každého prvku přidaného do rozhraní API se předpokládá, že obsahuje svou vlastní značku @since a informaci o verzi.

Nástroje poskytují následující ověřování platnosti značek @since:

Předvolby správy značek @since lze upravovat na stránce předvoleb Otevírá stránku předvoleb konzoly Vývoj modulu plug-in > Chyby/varování API.

Chybějící značky @since

Pro každý nově rozpoznaný prvek API nástroje ověří, zda obsahuje značku @since. Pokud nový prvek neobsahuje značku @since, bude označen příznakem signalizujícím potřebu vložení značky a bude navržena verze pro značku. Pro novou značku bude navržena současná verze balíku s výjimkou zásadní změny rozhraní API, jež vyžaduje i aktualizaci verze balíku. Pokud verze balíku vyžaduje aktualizaci, bude pro chybějící značku @since navržena navržená verze balíku.

Věnujte pozornost tomuto příkladu: Mějme balík A s verzí 1.0.0 a dále třídu C, která byla přidána do verze 1.1.0 balíku A, jež obsahuje metodu m1().

Chybné značky @since

Pro nové prvky může být kontrolována konzistence značek @since pro ověření, zda jsou správě formulovány. Nástroje API ověřují, zda všechny značky @since respektují obecný formát:

[@since] [preambule] [verze ze dvou částí] [postambule]

Následují příklady značek @since:

Neplatné verze značky @since

Pro nové prvky může být ověřována rovněž platnost jejich značek @since. Značka @since je považována za platnou, pokud informace o verzi ve značce odpovídá verzi balíku.

Následuje příklad, ve kterém jsme přidali novou metodu m2() do třídy API v balíku A, jehož verze je 1.0.0:

Související úlohy
Nastavení úrovně baseline

Související odkazy
Předvolby úrovní baseline rozhraní API
Předvolby chyb a varování API