API-værktøjerne understøtter administration af @since
-koder i Javadoc på nye elementer, der er blevet tilføjet til API'et (typer, metoder, felter osv).
Nye API-elementer kunne være en ny type, der tilføjes til en API-pakke, en ny type, der tilføjes til en API-type, en ny metode, der tilføjes til en a API-type, eller et nyt felt, der tilføjes til en API-type.
Metodetilføjelse er et specialtilfælde, hvor en metodetilføjelse kan være tilføjelse af en metode til en type, tilsidesættelse af en overordnet klassemetode, implementering af en overordnet grænseflademetode eller ændring af en eksisterende metodes signatur.
Bemærk: @since
-kodeoplysninger spredes ikke via implementering eller oprettelse af underklasser. Alle elementer, der tilføjes til API'et, forventes at have deres egne @since
-koder og versionsoplysninger.
Værktøjerne giver mulighed for følgende validering af @since
-koder:
Indstillingerne for @since
-kodeadministration kan ændres på indstillingssiden Plugin-udvikling > API-fejl/advarsler.
Alle nye API-elementer, der registreres, bliver tjekket af værktøjet for at sikre, at de har en @since
-kode.
Hvis det nye element ikke har en @since
-kode, bliver det markeret som element, der mangler en kode, og der foreslås en version for koden.
Den foreslåede version for den nye kode bliver den aktuelle version af bundtet - bortset fra hvis der er tale om en API-brudændring, hvor versionen også skal opdateres. Hvis bundtversionen også skal opdateres, bliver den foreslåede version for den manglende @since
-kode samme version som den foreslåede bundtversion.
Et eksempel: Vi har et bundt, A, med version 1.0.0, og vi har en klasse, C, der blev tilføjet i version 1.1.0 af A, som indeholder metode m1().
@since
-kode på m2() og foreslå, at der placeres en ny kode af @since 1.1
på m2().@since
-kode på m2() og foreslå, at der placeres en ny kode af @since 2.0
på m2(), hvor 2.0.0
er den nye foreslåede bundtversion.
@since
-koderne i nye elementer kan tjekkes for konsekvens for at sikre, at de er formuleret korrekt. API-værktøjer tjekker, at alle @since
-koder følger det generelle format:
[@since] [præambel] [2 delversion] [postambel]
Se følgende eksempler på @since
-koder:
@since A 1 added m2()
: bliver markeret som forkert udformet, fordi versionen mangler i det andet segment@since
: markeres som forkert udformet, da der ikke er nogen versionsoplysninger@since A
: markeres, fordi der ikke er nogen versionsoplysninger@since 1.0.0
: markeres, fordi versionen har for mange segmenter@since A 1.0 added m2()
: markeres ikke
@since
-koderne i nye elementer kan også tjekkes for gyldighed. En @since
-kode anses for gyldig, hvis versionsoplysningerne i k oden matcher versionen af bundtet.
Se følgende eksempel, hvor vi har tilføjet en ny metode, m2(), til en API-klasse i bundt A, hvis version er 1.0.0:
@since A 1.0 added method m2()
: anses for gyldig@since A 2.0 added method m2()
: er ugyldig, da versionen af bundt A er 1.0.0@since A 0.1 added method m2()
: er ugyldig, da versionen af bundt A er 1.0.0
API-grundlinjeindstillinger
Indstillinger for API-fejl og -advarsler