streamalism.org

1. Pregled

Dobra API dokumentacija jedan je od mnogih čimbenika koji pridonose ukupnom uspjehu softverskog projekta.

Srećom, sve moderne verzije JDK pružaju Javadoc alat - za generiranje API dokumentacije iz komentara prisutnih u izvornom kodu.

Preduvjeti:

1. JDK 1.4 (JDK 7+ preporučuje se za najnoviju verziju dodatka Maven Javadoc)
2. JDK / kanta za smeće mapa dodana u STAZA varijabla okoline
3. (Neobvezno) IDE koji ima ugrađene alate

2. Javadoc komentari

Krenimo od komentara.

Javadoc struktura komentara izgleda vrlo slično uobičajenom višerednom komentaru, ali ključna razlika je dodatna zvjezdica na početku:

// Ovo je komentar u jednom retku / * * Ovo je redoviti komentar u više redova * / / ** * Ovo je Javadoc * /

Komentari u stilu Javadoc mogu sadržavati i HTML oznake.

2.1. Javadoc format

Javadoc komentari mogu se postaviti iznad bilo koje klase, metode ili polja koje želimo dokumentirati.

Ovi se komentari obično sastoje od dva odjeljka:

1. Opis onoga što komentiramo
2. Oznake samostalnih blokova (označene oznakom „@”Simbol) koji opisuju određene meta-podatke

U našem ćemo primjeru koristiti neke od uobičajenih oznaka blokova. Potpuni popis oznaka blokova potražite u referentnom vodiču.

2.2. Javadoc na razini predavanja

Pogledajmo kako bi izgledao Javadoc komentar na razini klase:

/ ** * Hero je glavni entitet na koji ćemo se služiti. . . * * Molimo pogledajte klasu {@link com.baeldung.javadoc.Person} za pravi identitet * @author Captain America * * / javna klasa SuperHero extends Person {// polja i metode}

Imamo kratki opis i dvije različite oznake blokova - samostalne i ugrađene:

• Samostalne oznake pojavljuju se nakon opisa s oznakom kao prvom riječi u retku, npr. @Autor označiti
• Umetnute oznake mogu se pojaviti bilo gdje i okružene su kovrčavim zagradama, npr @veza oznaka u opisu

U našem primjeru također možemo vidjeti dvije vrste blok oznaka koje se koriste:

• {@veza} pruža linijsku vezu do referenciranog dijela našeg izvornog koda
• @Autor ime autora koji je dodao razred, metodu ili polje koje se komentira

2.3. Javadoc na razini polja

Također možemo koristiti opis bez bilo kakvih blok oznaka poput ove unutar našeg Superheroj razred:

/ ** * Javno ime heroja koje je općepoznato * / private String heroName;

Privatna polja neće generirati Javadoc za njih ako izričito ne proslijedimo -privatni opcija za naredbu Javadoc.

2.4. Javadoc na razini metode

Metode mogu sadržavati razne Javadoc blok oznake.

Pogledajmo metodu koju koristimo:

/** * 
Ovo je jednostavan opis metode. . . * Superman! * 
 * @param incomingDamage iznos dolazne štete * @return količinu zdravstvenog heroja koju ima nakon napada * @see HERO-402 * @since 1.0 * / public int uspešnoAttacked (int incomingDamage) {// stvari se vraćaju 0; }

The uspješno napadnut metoda sadrži i opis i brojne samostalne oznake blokova.

Postoji mnogo blokovskih oznaka koje pomažu u generiranju odgovarajuće dokumentacije, a možemo uključiti sve vrste različitih vrsta podataka. U komentarima možemo koristiti i osnovne HTML oznake.

Krenimo s oznakama na koje nailazimo u gornjem primjeru:

• @param pruža bilo koji koristan opis parametra metode ili unosa koji bi trebao očekivati
• @povratak daje opis onoga što će se metoda vratiti ili može vratiti
• @vidjeti generirat će vezu sličnu {@veza} oznaka, ali više u kontekstu reference, a ne inline
• @od određuje koja je verzija razred, polje ili metoda dodana u projekt
• @verzija navodi verziju softvera, koja se obično koristi s% I% i% G% makronaredbama
• @baca koristi se za daljnje objašnjenje slučajeva u kojima bi softver mogao očekivati ​​iznimku
• @odgovoreno daje objašnjenje zašto je kôd zastario, kada je možda zastario i koje su alternative

Iako su oba odjeljka tehnički neobavezna, trebat će nam barem jedan za alat Javadoc da bi generirao bilo što značajno.

3. Javadoc generacija

Kako bismo generirali naše Javadoc stranice, htjeli bismo pogledati alat naredbenog retka koji se isporučuje s JDK i dodatak Maven.

3.1. Alat naredbenog retka Javadoc

Alat za naredbene retke Javadoc vrlo je moćan, ali ima određenu složenost.

Pokretanje naredbe javadoc bez ikakvih opcija ili parametara rezultirat će pogreškom i izlaznim parametrima koje očekuje.

Trebat ćemo barem navesti za koji paket ili klasu želimo generirati dokumentaciju.

Otvorimo naredbeni redak i idemo do direktorija projekta.

Pod pretpostavkom da su svi razredi u src mapa u direktoriju projekta:

[e-pošta zaštićena]: ~ $ javadoc -d doc src \ *

To će generirati dokumentaciju u direktoriju zvanom doc kako je navedeno s -d zastava. Ako postoji više paketa ili datoteka, trebat ćemo ih navesti sve.

Korištenje IDE-a s ugrađenom funkcionalnošću je, naravno, lakše i općenito se preporučuje.

3.2. Javadoc s dodatkom Maven

Također se možemo poslužiti dodatkom Maven Javadoc:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0 1.8 1.8 ... 

U osnovnom direktoriju projekta, izvodimo naredbu za generiranje našeg Javadocsa do direktorija na target \ site:

[zaštićena e-poštom]: ~ $ mvn javadoc: javadoc

Dodatak Maven vrlo je moćan i omogućuje neometano generiranje složenih dokumenata.

Pogledajmo sada kako izgleda generirana Javadoc stranica:

Možemo vidjeti pogled na stablo naše nastave Superheroj razred se proteže. Možemo vidjeti svoj opis, polja i metodu, a za dodatne informacije možemo kliknuti na poveznice.

Detaljan prikaz naše metode izgleda ovako:

3.3. Prilagođene Javadoc oznake

Pored upotrebe unaprijed definiranih blokovskih oznaka za formatiranje naše dokumentacije, možemo stvoriti i prilagođene oznake blokova.

Da bismo to učinili, samo trebamo uključiti a -označiti opcija za naš Javadoc naredbeni redak u formatu ::.

Da bi se stvorila prilagođena oznaka zvana @mjesto dopušteno bilo gdje, što je prikazano u zaglavlju "Značajne lokacije" u našem generiranom dokumentu, moramo pokrenuti:

[zaštićena e-poštom]: ~ $ javadoc -tag mjesto: a: "Značajne lokacije:" -d doc src \ *

Da bismo koristili ovu oznaku, možemo je dodati u blok odjeljak Javadoc komentara:

/ ** * Ovo je primjer ... * @location New York * @returns blah blah * /

Dodatak Maven Javadoc dovoljno je fleksibilan da dopušta i definicije naših prilagođenih oznaka u našem pom.xml.

Kako bismo postavili istu oznaku za naš projekt, možemo dodati sljedeće u odjeljak našeg dodatka:

... mjesto a Značajna mjesta: ...

Ovaj način omogućuje nam da jednom odredimo prilagođenu oznaku, umjesto da je odredimo svaki put.

4. Zaključak

Ovaj brzi uvodni priručnik obuhvatio je kako napisati osnovne Javadocs i generirati ih pomoću naredbenog retka Javadoc.

Jednostavniji način generiranja dokumentacije bio bi korištenje bilo koje ugrađene IDE opcije ili uključivanje dodatka Maven u naš pom.xml datoteku i pokrenite odgovarajuće naredbe.

Uzorci koda, kao i uvijek, mogu se naći na GitHubu.