Share
Deze snelle les behandelt Javadoc, een handig hulpmiddel voor het genereren van documentatie van uw Java-bronbestanden. Deze les maakt deel uit van een doorlopende reeks tutorials voor ontwikkelaars die Java leren om Android-applicaties te ontwikkelen.
Javadoc is een hulpprogramma dat wordt meegeleverd met de Java SDK, waarmee ontwikkelaars codedocumentatie van Java-bronbestanden kunnen genereren. Ontwikkelingsomgevingen zoals Eclipse hebben ingebouwde ondersteuning voor Javadoc en kunnen doorzoekbare HTML-referentiematerialen genereren op basis van Javadoc-achtige opmerkingen. In feite is de Android SDK-referentie een vorm van Javadoc-documentatie.
Javadoc-documentatie maakt gebruik van een combinatie van het verwerken van de broncode (en het inspecteren van typen, parameters, enz.) En het lezen van speciale commentaartags die de ontwikkelaar biedt als metadata geassocieerd met een deel van de code.
Een opmerking in Javadoc-stijl moet vlak voor de code komen waaraan deze is gekoppeld. Een Javadoc-opmerking voor een klasse moet bijvoorbeeld net boven de klassenverklaring staan en een opmerking voor een methode moet net boven de methodeaangifte staan. Elke opmerking zou moeten beginnen met een korte beschrijving, gevolgd door een langere beschrijving van de optie. Vervolgens kunt u een aantal verschillende metadatatags toevoegen, die in een specifieke volgorde moeten worden geleverd. Enkele belangrijke tags zijn:
U kunt ook uw eigen aangepaste tags maken voor gebruik in documentatie.
Terwijl je code schrijft in Eclipse, kun je een opmerking in Javadoc-stijl genereren door het item te selecteren dat je wilt commentariëren (een klassenaam, methode naam, etc.) en Alt-Shift-J in te drukken (Cmd-Shift-J op een Mac). Dit zal een basis Javadoc-achtige opmerking voor u maken om de details in te vullen.
Laten we een voorbeeld bekijken. Hier is een eenvoudige Javadoc-opmerking die een klasse beschrijft:
/ ** * Activiteit voor het laden van lay-outbronnen * * Deze activiteit wordt gebruikt om verschillende lay-outresources weer te geven voor een zelfstudie over het ontwerp van de gebruikersinterface. * * @author LED * @version 2010.1105 * @since 1.0 * / public class LayoutActivity breidt activiteit uit
Hier is hoe het eruit zal zien wanneer u de Javadoc-documentatie genereert:
Laten we een voorbeeld bekijken. Hier is een eenvoudige Javadoc-opmerking die een veld in een klasse beschrijft:
/ ** * Foutopsporingscode voor gebruik logboekregistratie foutopsporingsuitvoer naar LogCat * / statische privéafsluiting String DEBUG_TAG = "MyActivityDebugTag";
Hier is hoe het eruit zal zien wanneer u de Javadoc-documentatie genereert:
Laten we nu eens kijken naar twee voorbeelden van opmerkingen over de methode. Hier is een eenvoudige Javadoc-opmerking die een methode beschrijft binnen een klasse:
/ ** * Methode die twee gehele getallen bij elkaar optelt * * @param a Het eerste gehele getal om toe te voegen * @param b Het tweede gehele getal om toe te voegen * @return De resulterende som van a en b * / openbare int addIntegers (int a, int b ) return (a + b);
Laten we nu eens kijken naar een methode die ongeldig is, maar een uitzondering genereert:
/ ** * Deze methode gooit gewoon een uitzondering als de inkomende parameter a geen positief getal is, alleen voor de lol. * * @param a Om wel of geen uitzondering te maken * @throws Exception * / public void throwException (boolean shouldThrow) gooit Exception if (shouldThrow == true) throw new Exception ();
Hier is hoe het eruit zal zien wanneer u de Javadoc-documentatie genereert voor deze twee methoden:
Als u Javadoc-codedocumentatie wilt genereren in Eclipse, gaat u naar het menu Project en kiest u de optie "Javadoc genereren ...". Hiermee start u een wizard waarmee u de projecten kunt kiezen om documentatie voor te genereren.
Vanuit deze wizard moet je Eclipse naar het juiste opdrachtregelprogramma javadoc.exe wijzen (je vindt het in de directory / bin van je JDK). U kunt ook enkele documentatie-instellingen configureren, bijvoorbeeld of alle code moet worden gedocumenteerd of alleen zichtbare klassen, leden, enz. Kies ten slotte een bestemming voor uw documentatiebestanden.
Zelfs zonder de Javadoc-bestanden te genereren, zal Eclipse de Javadoc-achtige documentatie tonen wanneer je je muis over je methoden en dergelijke beweegt, zoals te zien is in de onderstaande figuur.
U kunt meer informatie vinden op de Javadoc-referentie op de Oracle-website. Er is ook een handige Javadoc FAQ beschikbaar.
In deze korte les hebt u kennisgemaakt met Javadoc, een krachtig hulpmiddel dat door Java-ontwikkelaars wordt gebruikt om de broncode grondig te documenteren voor referentie- en onderhoudsdoeleinden. Eclipse, de ontwikkelomgeving die door veel Android-ontwikkelaars wordt gebruikt, heeft ingebouwde ondersteuning voor Javadoc.
Mobiele ontwikkelaars Lauren Darcey en Shane Conder hebben samen meerdere boeken geschreven over Android-ontwikkeling: een diepgaand programmeerboek getiteld Android Wireless Application Development en Sams TeachYourself Android Application Development binnen 24 uur. Wanneer ze niet schrijven, besteden ze hun tijd aan het ontwikkelen van mobiele software bij hun bedrijf en het leveren van consultingservices. Ze zijn te bereiken via e-mail naar [email protected], via hun blog op androidbook.blogspot.com, en op Twitter @androidwireless.
Accentsconagua