Share
Den här snabba lektionen täcker Javadoc, ett användbart verktyg för att generera dokumentation från dina Java-källfiler. Denna lektion är en del av en pågående serie av handledning för utvecklare som lär sig Java för att utveckla Android-applikationer.
Javadoc är ett verktyg som tillhandahålls av Java SDK som tillåter utvecklare att generera koddokumentation från Java-källfiler. Utvecklingsmiljöer som Eclipse har inbyggt stöd för Javadoc och kan generera sökbara HTML-referensmaterial från Javadoc-stilkommentarer. Faktum är att Android SDK-referensen är en form av Javadoc-dokumentation.
Javadoc-dokumentationen använder en kombination av att hantera källkoden (och inspekterar typer, parametrar etc.) och läser speciella kommentarkoder som utvecklaren tillhandahåller som metadata förknippade med en sektion av kod.
En kommentar från Javadoc-stilen måste komma precis före koden den är förknippad med. Exempelvis bör en Javadoc-kommentar för en klass vara precis ovanför klassdeklarationen och en kommentar för en metod bör vara precis ovanför metoddeklarationen. Varje kommentar bör börja med en kort beskrivning, följt av en alternativ längre beskrivning. Då kan du inkludera ett antal olika metadatakoder, som måste levereras i en viss ordning. Några viktiga taggar är:
Du kan också skapa egna anpassade taggar för användning i dokumentation.
Medan du skriver kod i Eclipse kan du skapa en Javadoc-stilkommentar genom att välja objektet du vill kommentera (ett klassnamn, metodnamn etc.) och trycka på Alt-Shift-J (Cmd-Shift-J på en Mac). Detta kommer att skapa en grundläggande Javadoc-stil kommentar för att fylla i detaljerna.
Låt oss titta på ett exempel. Här är en enkel Javadoc-kommentar som beskriver en klass:
/ ** * Aktivitet för att ladda upp layoutresurser * * Den här aktiviteten används för att visa olika layoutresurser för en handledning om användargränssnitt. * * @author LED * @version 2010.1105 * @since 1.0 * / public class LayoutActivity utökar aktivitet
Så här kommer det att se ut när du skapar Javadoc-dokumentationen:
Låt oss titta på ett exempel. Här är en enkel Javadoc-kommentar som beskriver ett fält inom en klass:
/ ** * Debug Tag för användning logga debug output till LogCat * / privat statisk slutsträng DEBUG_TAG = "MyActivityDebugTag";
Så här kommer det att se ut när du skapar Javadoc-dokumentationen:
Låt oss nu titta på två exempel på metodkommentarer. Här är en enkel Javadoc-kommentar som beskriver en metod inom en klass:
/ ** * Metod som lägger till två heltal tillsammans * * @param a Det första heltalet för att lägga till * @param b Det andra heltalet för att lägga till * @return Den resulterande summan av a och b * / public int addIntegers (int a, int b ) retur (a + b);
Låt oss nu titta på en metod som returnerar ogiltig, men kastar ett undantag:
/ ** * Denna metod kastar bara en Undantag om den inkommande parametern a inte är ett positivt tal, bara för skojs skull. * * @param a Oavsett om man vill undvika ett undantag * @throws Undantag * / offentligt tomt kastException (booleska shouldThrow) kastar Undantag om (shouldThrow == true) kasta ny Undantag ();
Så här kommer det att se ut när du skapar Javadoc-dokumentationen för dessa två metoder:
För att skapa Javadoc-koddokumentation i Eclipse, gå till Project-menyn och välj alternativet "Generera Javadoc ...". Detta startar en guide som låter dig välja vilka projekt som ska generera dokumentation för.
Från den här guiden bör du peka Eclipse på det lämpliga javadoc.exe kommandoradsverktyget (du hittar det i din JDK / bin-katalog). Du kan också konfigurera några dokumentationsinställningar, till exempel om du vill dokumentera all kod eller bara synliga klasser, medlemmar etc. Slutligen, välj en destination för dina dokumentationsfiler.
Även utan att skapa Javadoc-filerna kommer Eclipse att visa Javadoc-dokumentationen när du svävar över dina metoder och så som visas i figuren nedan.
Du kan läsa mer av Javadoc-referensen på Oracle-webbplatsen. Det finns också en användbar Javadoc FAQ som finns tillgänglig.
I den här snabba lektionen har du lärt dig Javadoc, ett kraftfullt verktyg som används av Java-utvecklare för att dokumentera källkoden noggrant för referens- och underhållsändamål. Eclipse, utvecklingsmiljön som används av många Android-utvecklare, har inbyggt stöd för Javadoc.
Mobila utvecklare Lauren Darcey och Shane Conder har medverkat flera böcker om Android-utveckling: en fördjupad programmeringsbok med titeln Android Wireless Application Development och Sams TeachYourself Android Application Development inom 24 timmar. När de inte skriver, spenderar de sin tid på att utveckla mobil mjukvara hos sina företag och tillhandahålla konsulttjänster. De kan nås via e-post till [email protected], via deras blogg på androidbook.blogspot.com, och på Twitter @ androidwireless.
Accentsconagua