Hvordan lage Javadoc Når Kommenterer

Javadoc er de facto standard for generering av dokumentasjon fra kildekode. Det er et verktøy for å lage HTML dokumentasjon fra spesielt formatert kommentarer i Java-kode. Dette kan brukes til å generere strukturert programmeringsgrensesnitt (API) dokumentasjon automatisk gi noen hint til IDE eller for tildeling av pakker, klasser og metoder. I hovedsak er det en måte å kommentere parameterbeskrivelser, som skrev hva, og hvem som har skylden hvis det bryter. Java kommer med javadoc kommandolinje program for å generere HTML-dokumentasjon, men de fleste Java integrerte utviklingsmiljøer (IDE) har også denne integrert.

Bruksanvisning

1 Lag spesielle javadoc kommentarer. Å betegne en javadoc kommentar, starte kommentaren med /. Javadoc kommentarer vanligvis finnes på toppen av en fil, før klasser og før metoder. Siden det er designet for fullt API-dokumentasjon, er det ikke uvanlig å se filer med flere javadoc kommentarer enn kode. ""/

Dette er en javadoc kommentar. Det har ikke noen javadoc meta-tags ennå, men det gjorde utløse javadoc parser for å ta en titt på denne kommentaren.
/ ""

2 Legg API meta-tags (tags som beskriver API selv) når du kommenterer. API-koder er parameternavn, beskrivelser, unntaks profiler, returverdi beskrivelser, metodenavn og metodebeskrivelser. Mange IDE innlemme disse dataene inn i sine verktøytips og andre hjelpere, samt at det er for bruk i HTML eller kommentar form.

3 Bruk metodebeskrivelse. Denne meta-tag har ingen kodenavn: Det er rett og slett den kommentaren som kommer før de andre koder. ""/*


 Computes the slope of a line.
*/"" ""/*
Computes the slope of a line.
*/""

4 Innlemme parameterbeskrivelser. Disse er merket med de @param meta-tags, som bør følges av et parameternavn og beskrivelse. ""/*


 Computes the slope of a line.

 @param p1 First point that describes the line
@param p2 Second point that describes the line
 /"" ""/*
Computes the slope of a line.

 @param p1 First point that describes the line
@param p2 Second point that describes the line
 /""

5 Returverdi beskrivelser. Denne er merket med @return meta-tag og bør følges av en beskrivelse av returverdien. ""/*


 Computes the slope of a line.

 @param p1 First point that describes the line
@param p2 Second point that describes the line
 @return Slope of the line as a float
*/"" ""/*
Computes the slope of a line.

 @param p1 First point that describes the line
@param p2 Second point that describes the line
 @return Slope of the line as a float
*/""

6 Legg attribusjon koder. Kodene tilskriver koden til en bestemt forfatter. ""/*


 Computes the slope of a line.

 @Author Jack Smith
@param p1 First point that describes the line
 @param p2 Second point that describes the line
@return Slope of the line as a float
 /"" ""/*
Computes the slope of a line.

 @Author Jack Smith
@param p1 First point that describes the line
 @param p2 Second point that describes the line
@return Slope of the line as a float
 /""

7 Generere HTML-dokumentasjon. Hvis du ikke bruker en IDE eller du bare ønsker å gjøre det manuelt, kan du kjøre javadoc kommandolinjeprogrammet fra prosjektkatalogen. Spesifisere output katalog med -d bryteren og gi det en liste over .java filer (vanligvis som et wildcard). ""javadoc -d docs *.java""

Hint

  • Når du bruker en IDE, er HTML dokumentasjon sannsynligvis gjøres automatisk som en del av byggeprosessen. Se i IDE dokumentasjon for å bekrefte dette.
  • Multi-line kommentarer i Java tradisjonelt starter med /
  • , Men den ekstra stjerne tegnet i Javadoc signaliserer javadoc parser for å begynne å lete etter javadoc meta-tags.