Styring av @since-koder i Javadoc

API-verktøy gir mulighet til å håndtere Javadocs @since-koder som er lagt til APIen (typer, metoder, felter osv.). Nye API-elementer kan være en ny type som er lagt til en API-pakke, en ny type som er lagt til en API-type, en ny metode som er lagt til en API-type, eller et nytt felt som er lagt til en API-type. Tilføying av nye metoder er et spesialtilfelle, da en ny metode kan legges til en type og dermed overstyre metoden i en overordnet klasse, implementere en overordnet grensesnittmetode eller endre signaturen til en eksisterende metode.

Merk: @since-kodeinformasjon propageres ikke via implementering eller underordnede klasser. Alle elementer som legges til en API forventes å ha sin egen @since-kode og versjonsinformasjon.

Verktøyene gir følgende validering av @since-koder:

Preferansene for @since-kodeadministrasjon kan endres på Åpner preferansesiden for konsollen Plugin-utvikling > API-feil/-advarsler preferansesiden.

Manglende @since-koder

Alle nye API-elementer som oppdages, blir sjekket av verktøyet for å sikre at de har en @since-kode. Hvis det nye elementet ikke har en @since-kode, blir det flagget med at det trenger en, og en ny versjon foreslås for koden. Den foreslåtte versjonen til den nye koden blir den gjeldende versjonen av bunten, unntatt hvis det er en brytende API-endring hvor versjonen av bunten også må oppdateres. Hvis buntversjonen også må oppdateres, blir den foreslåtte versjonen til den manglende @since-koden den samme som den foreslåtte buntversjonen.

La oss se på følgende eksempel: vi har en bunt A med versjon 1.0.0, og vi har en klasse C som ble lagt til i versjon 1.1.0 av A som inneholder metoden m1().

@since-koder med feil format

Det er mulig å sjekke at @since-kodene til nye elementer er konsekvente, for å sikre at de er riktig formulert. API-verktøy sjekker at alle @since-koder følger det generelle formatet:

[@since] [preamble] [todelt versjon] [postamble]

Se på følgende @since-kodeeksempler:

Ugyldige @since-kodeversjoner

Nye elementer kan også få sjekket at @since-kodene deres er gyldige. En @since-kode anses som gydig hvis versjonsinformasjonen til koden stemmer med versjonen av bunten.

La oss se på følgende eksempel hvor vi har lagt til den nye metoden m2() i en API-klasse i bunt A med versjonen 1.0.0:

Beslektede oppgaver
Konfigurere en basis

Beslektet referanse
Preferanser for API-basis
Preferanser for API-feil og -advarsler