Share
Denne raske leksjonen dekker Javadoc, et nyttig verktøy for å generere dokumentasjon fra Java-kildefilene dine. Denne leksjonen er en del av en kontinuerlig serie av opplæringsprogrammer for utviklere som lærer Java for å utvikle Android-applikasjoner.
Javadoc er et verktøy som leveres med Java SDK som lar utviklere generere kodedokumentasjon fra Java-kildefiler. Utviklingsmiljøer som Eclipse har innebygd støtte for Javadoc og kan generere søkbare HTML-referansematerialer fra Javadoc-stilkommentarer. Faktisk er Android SDK-referansen en form for Javadoc-dokumentasjon.
Javadoc-dokumentasjonen bruker en kombinasjon av behandling av kildekoden (og inspeksjonstyper, parametere, etc.) og lesing av spesielle kommentarkoder som utvikleren gir som metadata knyttet til en del av koden.
En Javadoc-stilkommentar må komme like før koden den er knyttet til. For eksempel bør en Javadoc-kommentar for en klasse være like over klassedeklarasjonen, og en kommentar til en metode bør være like over metoden deklarasjonen. Hver kommentar bør begynne med en kort beskrivelse, etterfulgt av et alternativ lengre beskrivelse. Deretter kan du inkludere et antall forskjellige metadatakoder, som må leveres i en bestemt rekkefølge. Noen viktige koder er:
Du kan også lage dine egne tilpassede koder for bruk i dokumentasjon.
Mens du skriver kode i Eclipse, kan du generere en Javadoc-stilkommentar ved å velge elementet du vil kommentere (et klassenavn, metodenavn, etc.) og trykke Alt-Shift-J (Cmd-Shift-J på en Mac). Dette vil skape en grunnleggende Javadoc-stil kommentar for deg å fylle ut detaljene.
La oss se på et eksempel. Her er en enkel Javadoc-kommentar som beskriver en klasse:
/ ** * Aktivitet for lasting av layoutressurser * * Denne aktiviteten brukes til å vise forskjellige layoutressurser for en veiledning om brukergrensesnittdesign. * * @author LED * @version 2010.1105 * @since 1.0 * / public class LayoutActivity utvider Aktivitet
Slik ser det ut når du genererer Javadoc-dokumentasjonen:
La oss se på et eksempel. Her er en enkel Javadoc-kommentar som beskriver et felt i en klasse:
/ ** * Debug Tag for bruk logging feilsøking utdata til LogCat * / privat statisk endelig streng DEBUG_TAG = "MyActivityDebugTag";
Slik ser det ut når du genererer Javadoc-dokumentasjonen:
La oss nå se på to eksempler på metodekommentarer. Her er en enkel Javadoc-kommentar som beskriver en metode i en klasse:
/ ** * Metode som legger til to heltall sammen * * @param a Det første heltallet for å legge til * @param b Det andre heltallet for å legge til * @return Den resulterende summen av a og b * / offentlige int addIntegers (int a, int b ) retur (a + b);
La oss nå se på en metode som returnerer tom, men kaster et unntak:
/ ** * Denne metoden kaster bare en unntak dersom innkommende parameter a ikke er et positivt tall, bare for moro skyld. * * @param a Om du ikke skal kaste et unntak * @throws Unntak * / offentlig tomtkastingException (boolean shouldThrow) kaster Unntak hvis (shouldThrow == true) kaste ny unntak ();
Slik ser det ut når du genererer Javadoc-dokumentasjonen for disse to metodene:
For å generere Javadoc-kodedokumentasjon i Eclipse, gå til Prosjekt-menyen og velg alternativet "Generer Javadoc ...". Dette vil starte en veiviser som lar deg velge prosjekter for å generere dokumentasjon for.
Fra denne veiviseren bør du peke Eclipse på det riktige javadoc.exe kommandolinjeverktøyet (du finner det i din JDK / bin-katalog). Du kan også konfigurere noen dokumentasjonsinnstillinger, for eksempel om du vil dokumentere all kode, eller bare synlige klasser, medlemmer, etc. Endelig velger du en destinasjon for dokumentasjonsfilene dine.
Selv uten å generere Javadoc-filene, vil Eclipse vise Javadoc-dokumentasjonen når du svinger over metodene dine og slik som vist i figuren under.
Du kan finne ut mer fra Javadoc-referansen på Oracle-nettstedet. Det er også en nyttig Javadoc FAQ tilgjengelig.
I denne korte leksjonen har du lært om Javadoc, et kraftig verktøy som brukes av Java-utviklere til å dokumentere kildekoden grundig for referanse og vedlikehold. Eclipse, utviklingsmiljøet som brukes av mange Android-utviklere, har innebygd støtte for Javadoc.
Mobilutviklere Lauren Darcey og Shane Conder har medforfatter flere bøker om Android-utvikling: en grundig programmeringsbok med tittel Android Wireless Application Development og Sams TeachYourself Android Application Development i 24 timer. Når de ikke skriver, bruker de sin tid på å utvikle mobil programvare hos deres firma og tilby konsulenttjenester. De kan nås via e-post til [email protected], via bloggen deres på androidbook.blogspot.com, og på Twitter @androidwireless.
Accentsconagua