Javadoc-The Java API Documentation Generator

19/03/2017 javadocTheJavaAPIDocumentationGenerator
javadocTheJavaAPIDocumentationGenerator
GeneratesHTMLpagesofAPIdocumentationfromJavasourcefiles.ThisdocumentcontainsJavadocexamplesforMicrosoftWindows.
CONTENTS
ReferenceGuide
Synopsis
Description
ProcessingofSourceFiles
JavadocDoclets
RelatedDocumentation
Terminology
SourceFiles
ClassSourceCodeFiles
PackageCommentFiles
OverviewCommentFile
MiscellaneousUnprocessedFiles
TestFilesandTemplateFiles
GeneratedFiles
GeneratedAPIDeclarations
DocumentationComments
CommentingtheSourceCode
AutomaticCopyingofMethodComments
JavadocTags(@tag)
WhereTagsCanBeUsed
Options(option)
JavadocOptions
OptionsProvidedbytheStandardDoclet
CommandLineArgumentFiles
Running
RunningJavadoc
http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html 1/48
SimpleExamples
DocumentingOneorMorePackages
DocumentingOneorMoreClasses
DocumentingBothPackagesandClasses
RealWorldExample
CommandLineExample
MakefileExample
Troubleshooting
GeneralTroubleshooting
ErrorsandWarnings
Environment
CLASSPATH
Troubleshooting
SeeAlso
ReferenceGuide
SYNOPSIS
javadoc[options][packagenames][sourcefilenames][subpackagespkg1:pkg2:...][@argfiles]
Argumentscanbeinanyorder.SeeprocessingofSourceFilesfordetailsonhowtheJavadoctooldetermineswhich".java"filestoprocess.
options
Commandlineoptions,asspecifiedinthisdocument.Toseeatypicaluseofjavadocoptions,seeRealWorldExample.
packagenames
Aseriesofnamesofpackages,separatedbyspaces,suchasjava.langjava.lang.reflectjava.awt.Youmustseparatelyspecifyeachpackageyouwanttodocument.
Wildcardsarenotallowedusesubpackagesforrecursion.TheJavadoctoolusessourcepathtolookforthesepackagenames.SeeExampleDocumentingOneorMore
Packages
sourcefilenames
Aseriesofsourcefilenames,separatedbyspaces,eachofwhichcanbeginwithapathandcontainawildcardsuchasasterisk(*).TheJavadoctoolwillprocesseveryfilewhose
nameendswith".java",andwhosename,whenstrippedofthatsuffix,isactuallyalegalclassname(seeinformationaboutIdentifiersintheJavaLanguageSpecification).Therefore,
youcannamefileswithdashes(suchasXBuffer),orotherillegalcharacters,topreventthemfrombeingdocumented.ThisisusefulfortestfilesandtemplatefilesThepaththat
precedesthesourcefilenamedetermineswherejavadocwilllookforthefile.(TheJavadoctooldoesnotusesourcepathtolookforthesesourcefilenames.)Relativepathsare
relativetothecurrentdirectory,sopassinginButton.javaisidenticalto./Button.java.Asourcefilenamewithanabsolutepathandawildcard,forexample,is
/home/src/java/awt/Graphics*.java.SeeExampleDocumentingOneorMoreClasses.Youcanalsomixpackagenamesandsourcefilenames,asinExampleDocumenting
BothPackagesandClasses
subpackagespkg1:pkg2:...
Generatesdocumentationfromsourcefilesinthespecifiedpackagesandrecursivelyintheirsubpackages.Analternativetosupplyingpackagenamesorsourcefilenames.
@argfiles
OneormorefilesthatcontainalistofJavadocoptions,packagenamesandsourcefilenamesinanyorder.Wildcards(*)andJoptionsarenotallowedinthesefiles.
DESCRIPTION
TheJavadoctoolparsesthedeclarationsanddocumentationcommentsinasetofJavasourcefilesandproducesacorrespondingsetofHTMLpagesdescribing(bydefault)thepublic
andprotectedclasses,nestedclasses(butnotanonymousinnerclasses),interfaces,constructors,methods,andfields.YoucanuseittogeneratetheAPI(ApplicationProgramming
Interface)documentationortheimplementationdocumentationforasetofsourcefiles.
YoucanruntheJavadoctoolonentirepackages,individualsourcefiles,orboth.Whendocumentingentirepackages,youcaneitherusesubpackagesfortraversingrecursivelydownfrom
atopleveldirectory,orpassinanexplicitlistofpackagenames.Whendocumentingindividualsourcefiles,youpassinalistofsource(.java)filenames.Examplesaregivenattheendof
thisdocument.HowJavadocprocessessourcefilesiscoverednext.
Processingofsourcefiles
TheJavadoctoolprocessesfilesthatendin".java"plusotherfilesdescribedunderSourceFiles.IfyouruntheJavadoctoolbyexplicitlypassinginindividualsourcefilenames,youcan
determineexactlywhich".java"filesareprocessed.However,thatisnothowmostdeveloperswanttowork,asitissimplertopassinpackagenames.TheJavadoctoolcanberunthree
wayswithoutexplicitlyspecifyingthesourcefilenames.Youcan(1)passinpackagenames,(2)usesubpackages,and(3)usewildcardswithsourcefilenames(*.java).Inthesecases,
theJavadoctoolprocessesa".java"fileonlyifitfulfillsallofthefollowingrequirements:
Itsname,afterstrippingoffthe".java"suffix,isactuallyalegalclassname(seetheJavaLanguageSpecificationforlegalcharacters)
Itsdirectorypathrelativetotherootofthesourcetreeisactuallyalegalpackagename(afterconvertingitsseparatorstodots)
Itspackagestatementcontainsthelegalpackagename(specifiedinthepreviousbullet)
ProcessingoflinksDuringarun,theJavadoctoolautomaticallyaddscrossreferencelinkstopackage,classandmembernamesthatarebeingdocumentedaspartofthatrun.Links
appearinseveralplaces:
Declarations(returntypes,argumenttypes,fieldtypes)
"SeeAlso"sectionsgeneratedfrom@seetags
Inlinetextgeneratedfrom{@link}tags
Exceptionnamesgeneratedfrom@throwstags
"Specifiedby"linkstomembersininterfacesand"Overrides"linkstomembersinclasses
Summarytableslistingpackages,classesandmembers
Packageandclassinheritancetrees
Theindex
Youcanaddhyperlinkstoexistingtextforclassesnotincludedonthecommandline(butgeneratedseparately)bywayofthelinkandlinkofflineoptions.
OtherprocessingdetailsTheJavadoctoolproducesonecompletedocumenteachtimeitisrunitcannotdoincrementalbuildsthatis,itcannotmodifyordirectlyincorporateresults
frompreviousrunsoftheJavadoctool.However,itcanlinktoresultsfromotherruns,asjustmentioned.
Asimplemented,theJavadoctoolrequiresandreliesonthejavacompilertodoitsjob.TheJavadoctoolcallspartofjavactocompilethedeclarations,ignoringthemember
implementation.Itbuildsarichinternalrepresentationoftheclasses,includingtheclasshierarchy,and"use"relationships,thengeneratestheHTMLfromthat.TheJavadoctoolalsopicks
upusersupplieddocumentationfromdocumentationcommentsinthesourcecode.
Infact,theJavadoctoolwillrunon.javasourcefilesthatarepurestubfileswithnomethodbodies.ThismeansyoucanwritedocumentationcommentsandruntheJavadoctoolinthe
earlieststagesofdesignwhilecreatingtheAPI,beforewritingtheimplementation.
RelyingonthecompilerensuresthattheHTMLoutputcorrespondsexactlywiththeactualimplementation,whichmayrelyonimplicit,ratherthanexplicit,sourcecode.Forexample,the
Javadoctooldocumentsdefaultconstructors(seetheJavaLanguageSpecification)thatarepresentinthe.classfilesbutnotinthesourcecode.
Inmanycases,theJavadoctoolallowsyoutogeneratedocumentationforsourcefileswhosecodeisincompleteorerroneous.Thisisabenefitthatenablesyoutogeneratedocumentation
beforealldebuggingandtroubleshootingisdone.Forexample,accordingtotheJavaLanguageSpecification,aclassthatcontainsanabstractmethodshoulditselfbedeclaredabstract.
TheJavadoctooldoesnotcheckforthis,andwouldproceedwithoutawarning,whereasthejavaccompilerstopsonthiserror.TheJavadoctooldoesdosomeprimitivecheckingofdoc
comments.UsetheDocCheckdoclettocheckthedoccommentsmorethoroughly.
WhentheJavadoctoolbuildsitsinternalstructureforthedocumentation,itloadsallreferencedclasses.Becauseofthis,theJavadoctoolmustbeabletofindallreferencedclasses,
whetherbootstrapclasses,extensions,oruserclasses.Formoreaboutthis,seeHowClassesAreFound.Generallyspeaking,classesyoucreatemusteitherbeloadedasanextensionor
intheJavadoctool'sclasspath.
JavadocDoclets
YoucancustomizethecontentandformatoftheJavadoctool'soutputbyusingdoclets.TheJavadoctoolhasadefault"builtin"doclet,calledthestandarddoclet,thatgeneratesHTML
formattedAPIdocumentation.Youcanmodifyorsubclassthestandarddoclet,orwriteyourowndoclettogenerateHTML,XML,MIF,RTForwhateveroutputformatyou'dlike.Information
aboutdocletsandtheiruseisatthefollowinglocations:
JavadocDoclets
Thedocletcommandlineoption
Whenacustomdocletisnotspecifiedwiththedocletcommandlineoption,theJavadoctoolwillusethedefaultstandarddoclet.Thejavadoctoolhasseveralcommandlineoptionsthat
areavailableregardlessofwhichdocletisbeingused.Thestandarddocletaddsasupplementarysetofcommandlineoptions.Bothsetsofoptionsaredescribedbelowintheoptions
section.
RelatedDocumentationandDoclets
JavadocEnhancementsfordetailsaboutimprovementsaddedinJavadoc.
JavadocFAQforanswerstocommonquestions,informationaboutJavadocrelatedtools,andworkaroundsforbugs.
HowtoWriteDocCommentsforJavadocformoreinformationaboutSunconventionsforwritingdocumentationcomments.
RequirementsforWritingAPISpecificationsStandardrequirementsusedwhenwritingtheJavaSEPlatformSpecification.ItcanbeusefulwhetheryouarewritingAPIspecificationsin
sourcefiledocumentationcommentsorinotherformats.Itcoversrequirementsforpackages,classes,interfaces,fieldsandmethodstosatisfytestableassertions.
DocumentationCommentSpecificationTheoriginalspecificationondocumentationcomments,Chapter18,DocumentationComments,intheJavaLanguageSpecification,First
Edition,byJamesGosling,BillJoy,andGuySteele.(Thischapterwasremovedfromthesecondedition.)
Terminology
Thetermsdocumentationcomment,doccomment,maindescription,tag,b locktag,andinlinetagaredescribedatDocumentationComments.Theseothertermshavespecificmeanings
withinthecontextoftheJavadoctool:
generateddocument
ThedocumentgeneratedbythejavadoctoolfromthedoccommentsinJavasourcecode.ThedefaultgenerateddocumentisinHTMLandiscreatedbythestandarddoclet.
name
AnameofaprogramelementwrittenintheJavaLanguagethatis,thenameofapackage,class,interface,field,constructorormethod.Anamecanbefullyqualified,suchas
java.lang.String.equals(java.lang.Object),orpartiallyqualified,suchasequals(Object).
documentedclasses
Theclassesandinterfacesforwhichdetaileddocumentationisgeneratedduringajavadocrun.Tobedocumented,thesourcefilesmustbeavailable,theirsourcefilenamesor
packagenamesmustbepassedintothejavadoccommand,andtheymustnotbefilteredoutbytheiraccessmodifier(public,protected,packageprivateorprivate).Wealsoreferto
theseastheclassesincludedinthejavadocoutput,ortheincludedclasses.
includedclasses
ClassesandinterfaceswhosedetailsaredocumentedduringarunoftheJavadoctool.Sameasdocumentedclasses.
excludedclasses
ClassesandinterfaceswhosedetailsarenotdocumentedduringarunoftheJavadoctool.
referencedclasses
Theclassesandinterfacesthatareexplicitlyreferredtointhedefinition(implementation)ordoccommentsofthedocumentedclassesandinterfaces.Examplesofreferences
includereturntype,parametertype,casttype,extendedclass,implementedinterface,importedclasses,classesusedinmethodbodies,@see,{@link},{@linkplain},and
{@inheritDoc}tags.(Noticethisdefinitionhaschangedsince1.3.)WhentheJavadoctoolisrun,itshouldloadintomemoryallofthereferencedclassesinjavadoc'sbootclasspath
andclasspath.(TheJavadoctoolprintsa"Classnotfound"warningforreferencedclassesnotfound.)TheJavadoctoolcanderiveenoughinformationfromthe.classfilesto
determinetheirexistenceandthefullyqualifiednamesoftheirmembers.
externalreferencedclasses
Thereferencedclasseswhosedocumentationisnotbeinggeneratedduringajavadocrun.Inotherwords,theseclassesarenotpassedintotheJavadoctoolonthecommandline.
Linksinthegenerateddocumentationtothoseclassesaresaidtobeexternalreferencesorexternallinks.Forexample,ifyouruntheJavadoctoolononlythejava.awtpackage,
thenanyclassinjava.lang,suchasObject,isanexternalreferencedclass.Externalreferencedclassescanbelinkedtousingthelinkandlinkofflineoptions.An
importantpropertyofanexternalreferencedclassisthatitssourcecommentsarenormallynotavailabletotheJavadocrun.Inthiscase,thesecommentscannotbeinherited.
SOURCEFILES
TheJavadoctoolwillgenerateoutputoriginatingfromfourdifferenttypesof"source"files:Javalanguagesourcefilesforclasses(.java),packagecommentfiles,overviewcommentfiles,
andmiscellaneousunprocessedfiles.Thissectionalsocoverstestfilesandtemplatefilesthatcanalsobeinthesourcetree,butwhichyouwanttobesurenottodocument.
ClassSourceCodeFiles
Eachclassorinterfaceanditsmemberscanhavetheirowndocumentationcomments,containedina.javafile.Formoredetailsaboutthesedoccomments,seeDocumentation
Comments.
PackageCommentFiles
Eachpackagecanhaveitsowndocumentationcomment,containedinitsown"source"file,thattheJavadoctoolwillmergeintothepackagesummarypagethatitgenerates.Youtypically
includeinthiscommentanydocumentationthatappliestotheentirepackage.
Tocreateapackagecommentfile,youhaveachoiceoftwofilestoplaceyourcomments:
packageinfo.javaCancontainapackagedeclaration,packageannotations,packagecommentsandJavadoctags.Thisfileisgenerallypreferredoverpackage.html.
package.htmlCancontainonlypackagecommentsandJavadoctags,nopackageannotations.
Apackagemayhaveasinglepackage.htmlfileorasinglepackageinfo.javafilebutnotboth.Placeeitherfileinthepackagedirectoryinthesourcetreealongwithyour.javafiles.
packageinfo.javaThisfilecancontainapackagecommentofthefollowingstructurethecommentisplacedbeforethepackagedeclaration:
File:java/applet/packageinfo.java
/**
*Providestheclassesnecessarytocreatean
*appletandtheclassesanappletuses
*tocommunicatewithitsappletcontext.
*
*Theappletframeworkinvolvestwoentities:
*theappletandtheappletcontext.
*Anappletisanembeddablewindow(seethe
*{@linkjava.awt.Panel}class)withafewextra
*methodsthattheappletcontextcanuseto
*initialize,start,andstoptheapplet.
*
*@since1.0
*@seejava.awt
*/
packagejava.lang.applet
Notethatwhilethecommentseparators/**and/*mustbepresent,theleadingasterisksontheintermediatelinescanbeomitted.package.htmlThisfilecancontainapackage
commentofthefollowingstructurethecommentisplacedinthe<body>element:
File:java/applet/package.html
<HTML>
<BODY>
Providestheclassesnecessarytocreateanappletandthe
classesanappletusestocommunicatewithitsappletcontext.

Theappletframeworkinvolvestwoentities:theapplet
andtheappletcontext.Anappletisanembeddable
window(seethe{@linkjava.awt.Panel}class)witha
fewextramethodsthattheappletcontextcanuseto
initialize,start,andstoptheapplet.
@since1.0
@seejava.awt
</BODY>
</HTML>
NoticethisisjustanormalHTMLfileanddoesnotincludeapackagedeclaration.ThecontentofthepackagecommentfileiswritteninHTML,likeallothercomments,withoneexception:
Thedocumentationcommentshouldnotincludethecommentseparators/**and*/orleadingasterisks.Whenwritingthecomment,youshouldmakethefirstsentenceasummaryabout
thepackage,andnotputatitleoranyothertextbetween<body>andthefirstsentence.Youcanincludepackagetagsaswithanydocumentationcomment,allblocktagsmustappearafter
themaindescription.Ifyouadda@seetaginapackagecommentfile,itmusthaveafullyqualifiedname.Formoredetails,seetheexampleofpackage.html.
ProcessingofpackagecommentfileWhentheJavadoctoolruns,itwillautomaticallylookforthepackagecommentfileiffound,theJavadoctooldoesthefollowing:
Copiesthecommentforprocessing.(Forpackage.html,copiesallcontentbetween<body>and</body>HTMLtags.Youcanincludea<head>sectiontoputa<title>,sourcefile
copyrightstatement,orotherinformation,butnoneofthesewillappearinthegenerateddocumentation.)
Processesanypackagetagsthatarepresent.
Insertstheprocessedtextatthebottomofthepackagesummarypageitgenerates,asshowninPackageSummary.
Copiesthefirstsentenceofthepackagecommenttothetopofthepackagesummarypage.Italsoaddsthepackagenameandthisfirstsentencetothelistofpackagesonthe
overviewpage,asshowninOverviewSummary.Theendofsentenceisdeterminedbythesamerulesusedfortheendofthefirstsentenceofclassandmembermaindescriptions.
OverviewCommentFile
Eachapplicationorsetofpackagesthatyouaredocumentingcanhaveitsownoverviewdocumentationcomment,keptinitsown"source"file,thattheJavadoctoolwillmergeintothe
overviewpagethatitgenerates.Youtypicallyincludeinthiscommentanydocumentationthatappliestotheentireapplicationorsetofpackages.
Tocreateanoverviewcommentfile,youcannamethefileanythingyouwant,typicallyoverview.htmlandplaceitanywhere,typicallyatthetoplevelofthesourcetree.Forexample,ifthe
sourcefilesforthejava.appletpackagearecontainedinC:\user\src\java\appletdirectory,youcouldcreateanoverviewcommentfileatC:\user\src\overview.html.
Noticeyoucanhavemultipleoverviewcommentfilesforthesamesetofsourcefiles,incaseyouwanttorunjavadocmultipletimesondifferentsetsofpackages.Forexample,youcouldrun
javadoconcewithprivateforinternaldocumentationandagainwithoutthatoptionforpublicdocumentation.Inthiscase,youcoulddescribethedocumentationaspublicorinternalinthe
firstsentenceofeachoverviewcommentfile.
Thecontentoftheoverviewcommentfileisonebigdocumentationcomment,writteninHTML,likethepackagecommentfiledescribedpreviously.Seethatdescriptionfordetails.Tore
iterate,whenwritingthecomment,youshouldmakethefirstsentenceasummaryabouttheapplicationorsetofpackages,andnotputatitleoranyothertextbetween<body>andthefirst
sentence.Youcanincludeoverviewtagsaswithanydocumentationcomment,alltagsexceptinlinetags,suchas{@link},mustappearafterthemaindescription.Ifyouadda@seetag,it
musthaveafullyqualifiedname.
WhenyouruntheJavadoctool,youspecifytheoverviewcommentfilenamewiththeoverviewoption.Thefileisthenprocessedsimilartothatofapackagecommentfile.
Copiesallcontentbetween<body>and</body>tagsforprocessing.
Processesanyoverviewtagsthatarepresent.
Insertstheprocessedtextatthebottomoftheoverviewpageitgenerates,asshowninOverviewSummary.
Copiesthefirstsentenceoftheoverviewcommenttothetopoftheoverviewsummarypage.
MiscellaneousUnprocessedFiles
YoucanalsoincludeinyoursourceanymiscellaneousfilesthatyouwanttheJavadoctooltocopytothedestinationdirectory.Thesetypicallyincludesgraphicfiles,exampleJavasource
(.java)andclass(.class)files,andselfstandingHTMLfileswhosecontentwouldoverwhelmthedocumentationcommentofanormalJavasourcefile.
Toincludeunprocessedfiles,puttheminadirectorycalleddocfileswhichcanbeasubdirectoryofanypackagedirectorythatcontainssourcefiles.Youcanhaveonesuchsubdirectory
foreachpackage.Youmightincludeimages,examplecode,sourcefiles,.classfiles,appletsandHTMLfiles.Forexample,ifyouwanttoincludetheimageofabuttonbutton.gifinthe
java.awt.Buttonclassdocumentation,youplacethatfileinthe/home/user/src/java/awt/docfiles/directory.Noticethedocfilesdirectoryshouldnotbelocatedat
/home/user/src/java/docfilesbecausejavaisnotapackagethatis,itdoesnotdirectlycontainanysourcefiles.
Alllinkstotheseunprocessedfilesmustbehardcoded,becausetheJavadoctooldoesnotlookatthefilesitsimplycopiesthedirectoryandallitscontentstothedestination.For
example,thelinkintheButton.javadoccommentmightlooklike:
/**
*Thisbuttonlookslikethis:
*<imgsrc="docfiles/Button.gif">
*/
TestFilesandTemplateFiles
Somedevelopershaveindicatedtheywanttostoretestfilesandtemplatesfilesinthesourcetreeneartheircorrespondingsourcefiles.Thatis,theywouldliketoputtheminthesame
directory,orasubdirectory,ofthosesourcefiles.
IfyouruntheJavadoctoolbyexplicitlypassinginindividualsourcefilenames,youcandeliberatelyomittestandtemplatesfilesandpreventthemfrombeingprocessed.However,ifyouare
passinginpackagenamesorwildcards,youneedtofollowcertainrulestoensurethesetestfilesandtemplatesfilesarenotprocessed.
Testfilesdifferfromtemplatefilesinthattheformerarelegal,compilablesourcefiles,whilethelatterarenot,butmayendwith".java".
TestfilesOftendeveloperswanttoputcompilable,runnabletestfilesforagivenpackageinthesamedirectoryasthesourcefilesforthatpackage.Buttheywantthetestfilestobelongtoa
packageotherthanthesourcefilepackage,suchastheunnamedpackage(sothetestfileshavenopackagestatementoradifferentpackagestatementfromthesource).Inthisscenario,
whenthesourceisbeingdocumentedbyspecifyingitspackagenamespecifiedonthecommandline,thetestfileswillcausewarningsorerrors.Youneedtoputsuchtestfilesina
subdirectory.Forexample,ifyouwanttoaddtestfilesforsourcefilesincom.package1,puttheminasubdirectorythatwouldbeaninvalidpackagename(becauseitcontainsahyphen):
com/package1/testfiles/
ThetestdirectorywillbeskippedbytheJavadoctoolwithnowarnings.
Ifyourtestfilescontaindoccomments,youcansetupaseparaterunoftheJavadoctooltoproducedocumentationofthetestfilesbypassingintheirtestsourcefilenameswithwildcards,
suchascom/package1/testfiles/*.java.
TemplatesforsourcefilesTemplatefileshavenamesthatoftenendin".java"andarenotcompilable.Ifyouhaveatemplateforasourcefilethatyouwanttokeepinthesourcedirectory,
youcannameitwithadash(suchasBufferTemplate.java),oranyotherillegalJavacharacter,topreventitfrombeingprocessed.ThisreliesonthefactthattheJavadoctoolwillonly
processsourcefileswhosename,whenstrippedofthe".java"suffix,isactuallyalegalclassname(seeinformationaboutIdentifiersintheJavaLanguageSpecification).
GENERATEDFILES
Bydefault,javadocusesastandarddocletthatgeneratesHTMLformatteddocumentation.Thisdocletgeneratesthefollowingkindsoffiles(whereeachHTML"page"correspondstoa
separatefile).Notethatjavadocgeneratesfileswithtwotypesofnames:thosenamedafterclasses/interfaces,andthosethatarenot(suchaspackagesummary.html).Filesinthelatter
groupcontainhyphenstopreventfilenameconflictswiththoseintheformergroup.
BasicContentPages
Oneclassorinterfacepage(classname.html)foreachclassorinterfaceitisdocumenting.
Onepackagepage(packagesummary.html)foreachpackageitisdocumenting.TheJavadoctoolwillincludeanyHTMLtextprovidedinafilenamedpackage.htmlorpackage
info.javainthepackagedirectoryofthesourcetree.
Oneoverviewpage(overviewsummary.html)fortheentiresetofpackages.Thisisthefrontpageofthegenerateddocument.TheJavadoctoolwillincludeanyHTMLtextprovidedin
afilespecifiedwiththeoverviewoption.Notethatthisfileiscreatedonlyifyoupassintojavadoctwoormorepackagenames.Forfurtherexplanation,seeHTMLFrames .)
CrossReferencePages
Oneclasshierarchypagefortheentiresetofpackages(overviewtree.html).Toviewthis,clickon"Overview"inthenavigationbar,thenclickon"Tree".
Oneclasshierarchypageforeachpackage(packagetree.html)Toviewthis,gotoaparticularpackage,classorinterfacepageclick"Tree"todisplaythehierarchyforthat
package.
One"use"pageforeachpackage(packageuse.html)andaseparateoneforeachclassandinterface(classuse/classname.html).Thispagedescribeswhatpackages,
classes,methods,constructorsandfieldsuseanypartofthegivenclass,interfaceorpackage.GivenaclassorinterfaceA,its"use"pageincludessubclassesofA,fieldsdeclaredas
A,methodsthatreturnA,andmethodsandconstructorswithparametersoftypeA.Youcanaccessthispagebyfirstgoingtothepackage,classorinterface,thenclickingonthe"Use"
linkinthenavigationbar.
AdeprecatedAPIpage(deprecatedlist.html)listingalldeprecatednames.(Adeprecatednameisnotrecommendedforuse,generallyduetoimprovements,andareplacement
nameisusuallygiven.DeprecatedAPIsmayberemovedinfutureimplementations.)
Aconstantfieldvaluespage(constantvalues.html)forthevaluesofstaticfields.
Aserializedformpage(serializedform.html)forinformationaboutserializableandexternalizableclasses.Eachsuchclasshasadescriptionofitsserializationfieldsand
methods.Thisinformationisofinteresttoreimplementors,nottodevelopersusingtheAPI.Whilethereisnolinkinthenavigationbar,youcangettothisinformationbygoingtoany
serializedclassandclicking"SerializedForm"inthe"Seealso"sectionoftheclasscomment.Thestandarddocletautomaticallygeneratesaserializedformpage:anyclass(publicor
nonpublic)thatimplementsSerializableisincluded,alongwithreadObjectandwriteObjectmethods,thefieldsthatareserialized,andthedoccommentsfromthe@serial,
@serialField,and@serialDatatags.Publicserializableclassescanbeexcludedbymarkingthem(ortheirpackage)with@serialexclude,andpackageprivateserializable
classescanbeincludedbymarkingthem(ortheirpackage)with@serialinclude.Asof1.4,youcangeneratethecompleteserializedformforpublicandprivateclassesbyrunning
javadocwithoutspecifyingtheprivateoption.
Anindex(index*.html)ofallclass,interface,constructor,fieldandmethodnames,alphabeticallyarranged.ThisisinternationalizedforUnicodeandcanbegeneratedasasingle
fileorasaseparatefileforeachstartingcharacter(suchasAZforEnglish).
SupportFiles
Ahelppage(helpdoc.html)thatdescribesthenavigationbarandtheabovepages.Youcanprovideyourowncustomhelpfiletooverridethedefaultusinghelpfile.
Oneindex.htmlfilewhichcreatestheHTMLframesfordisplay.Thisisthefileyouloadtodisplaythefrontpagewithframes.Thisfileitselfcontainsnotextcontent.
Severalframefiles(*frame.html)containinglistsofpackages,classesandinterfaces,usedwhenHTMLframesarebeingdisplayed.
Apackagelistfile(packagelist),usedbythelinkandlinkofflineoptions.Thisisatextfile,notHTML,andisnotreachablethroughanylinks.
Astylesheetfile(stylesheet.css)thatcontrolsalimitedamountofcolor,fontfamily,fontsize,fontstyleandpositioningonthegeneratedpages.
Adocfilesdirectorythatholdsanyimage,example,sourcecodeorotherfilesthatyouwantcopiedtothedestinationdirectory.ThesefilesarenotprocessedbytheJavadoctoolinany
mannerthatis,anyjavadoctagsinthemwillbeignored.Thisdirectoryisnotgeneratedunlessitexistsinthesourcetree.
HTMLFrames
TheJavadoctoolwillgenerateeithertwoorthreeHTMLframes,asshowninthefigurebelow.Itcreatestheminimumnecessarynumberofframesbyomittingthelistofpackagesifthereis
onlyonepackage(ornopackages).Thatis,whenyoupassasinglepackagenameorsourcefiles(*.java)belongingtoasinglepackageasargumentsintothejavadoccommand,itwill
createonlyoneframe(C)inthelefthandcolumnthelistofclasses.Whenyoupassintojavadoctwoormorepackagenames,itcreatesathirdframe(P)listingallpackages,aswellasan
overviewpage(Detail).Thisoverviewpagehasthefilenameoverviewsummary.html.Thus,thisfileiscreatedonlyifyoupassintwoormorepackagenames.Youcanbypassframesby
clickingonthe"NoFrames"linkorenteringatoverviewsummary.html.
IfyouareunfamiliarwithHTMLframes,youshouldbeawarethatframescanhavefocusforprintingandscrolling.Togiveaframefocus,clickonit.Thenonmanybrowsersthearrowkeys
andpagekeyswillscrollthatframe,andtheprintmenucommandwillprintit.
LoadoneofthefollowingtwofilesasthestartingpagedependingonwhetheryouwantHTMLframesornot:
index.html(forframes)
overviewsummary.html(fornoframes)
GeneratedFileStructure
ThegeneratedclassandinterfacefilesareorganizedinthesamedirectoryhierarchythatJavasourcefilesandclassfilesareorganized.Thisstructureisonedirectorypersubpackage.
Forexample,thedocumentgeneratedfortheclassjava.applet.Appletclasswouldbelocatedatjava\applet\Applet.html.Thefilestructureforthejava.appletpackagefollows,
giventhatthedestinationdirectoryisnamedapidocs.Allfilesthatcontaintheword"frame"appearintheupperleftorlowerleftframes,asnoted.AllotherHTMLfilesappearintheright
handframe.
NOTE:Directoriesareshowninbold.Theasterisks(*)indicatethefilesanddirectoriesthatareomittedwhentheargumentstojavadocaresourcefilenames(*.java)ratherthan
packagenames.Alsowhenargumentsaresourcefilenames,packagelistiscreatedbutisempty.Thedocfilesdirectorywillnotbecreatedinthedestinationunlessitexistsin
thesourcetree.
apidocsTopdirectory
index.htmlInitialpagethatsetsupHTMLframes
*overviewsummary.htmlListsallpackageswithfirstsentencesummaries
overviewtree.htmlListsclasshierarchyforallpackages
deprecatedlist.htmlListsdeprecatedAPIforallpackages
constantvalues.htmlListsvaluesofstaticfieldsforallpackages
serializedform.htmlListsserializedformforallpackages
*overviewframe.htmlListsallpackages,usedinupperleftframe
allclassesframe.htmlListsallclassesforallpackages,usedinlowerleftframe
helpdoc.htmlListsuserhelpforhowthesepagesareorganized
indexall.htmlDefaultindexcreatedwithoutsplitindexoption
indexfilesDirectorycreatedwithsplitindexoption
index<number>.htmlIndexfilescreatedwithsplitindexoption
packagelistListspackagenames,usedonlyforresolvingexternalrefs
stylesheet.cssHTMLstylesheetfordefiningfonts,colorsandpositions
javaPackagedirectory
appletSubpackagedirectory
Applet.htmlPageforAppletclass
AppletContext.htmlPageforAppletContextinterface
AppletStub.htmlPageforAppletStubinterface
AudioClip.htmlPageforAudioClipinterface
*packagesummary.htmlListsclasseswithfirstsentencesummariesforthispackage
*packageframe.htmlListsclassesinthispackage,usedinlowerlefthandframe
*packagetree.htmlListsclasshierarchyforthispackage
packageuseListswherethispackageisused
docfilesDirectoryholdingimageandexamplefiles
classuseDirectoryholdingpagesAPIisused
Applet.htmlPageforusesofAppletclass
AppletContext.htmlPageforusesofAppletContextinterface
AppletStub.htmlPageforusesofAppletStubinterface
AudioClip.htmlPageforusesofAudioClipinterface
srchtmlSourcecodedirectory
javaPackagedirectory
appletSubpackagedirectory
Applet.htmlPageforAppletsourcecode
AppletContext.htmlPageforAppletContextsourcecode
AppletStub.htmlPageforAppletStubsourcecode
AudioClip.htmlPageforAudioClipsourcecode
GeneratedAPIDeclarations
TheJavadoctoolgeneratesadeclarationatthestartofeachclass,interface,field,constructor,andmethoddescriptionforthatAPIitem.Forexample,thedeclarationfortheBooleanclass
is:
publicfinalclassBoolean
extendsObject
implementsSerializable
andthedeclarationfortheBoolean.valueOfmethodis:
publicstaticBooleanvalueOf(Strings)
TheJavadoctoolcanincludethemodifierspublic,protected,private,abstract,final,static,transient,andvolatile,butnotsynchronizedornative.Theselasttwo
modifiersareconsideredimplementationdetailandnotpartoftheAPIspecification.
Ratherthanrelyingonthekeywordsynchronized,APIsshoulddocumenttheirconcurrencysemanticsinthecomment'smaindescription,asin"asingleEnumerationcannotbeusedby
multiplethreadsconcurrently".Thedocumentshouldnotdescribehowtoachievethesesemantics.Asanotherexample,whileHashtableshouldbethreadsafe,there'snoreasonto
specifythatweachievethisbysynchronizingallofitsexportedmethods.Weshouldreservetherighttosynchronizeinternallyatthebucketlevel,thusofferinghigherconcurrency.
DOCUMENTATIONCOMMENTS
Theoriginal"DocumentationCommentSpecification"canbefoundunderrelateddocumentation.
CommentingtheSourceCode
Youcanincludedocumentationcomments("doccomments")inthesourcecode,aheadofdeclarationsforanyclass,interface,method,constructor,orfield.Youcanalsocreatedoc
commentsforeachpackageandanotheronefortheoverview,thoughtheirsyntaxisslightlydifferent.Doccommentsarealsoknowninformallyas"Javadoccomments"(butthisterm
violatesitstrademarkusage).Adoccommentconsistsofthecharactersbetweenthecharacters/**thatbeginthecommentandthecharacters*/thatendit.Leadingasterisksare
allowedoneachlineandaredescribedfurtherbelow.Thetextinacommentcancontinueontomultiplelines.
/**
*Thisisthetypicalformatofasimpledocumentationcomment
*thatspanstwolines.
*/
Tosavespaceyoucanputacommentononeline:
/**Thiscommenttakesuponlyoneline.*/
PlacementofcommentsDocumentationcommentsarerecognizedonlywhenplacedimmediatelybeforeclass,interface,constructor,method,orfielddeclarationsseetheclass
example,methodexample,andfieldexample.Documentationcommentsplacedinthebodyofamethodareignored.Onlyonedocumentationcommentperdeclarationstatementis
recognizedbytheJavadoctool.
Acommonmistakeistoputanimportstatementbetweentheclasscommentandtheclassdeclaration.Avoidthis,astheJavadoctoolwillignoretheclasscomment.
/**
*ThisistheclasscommentfortheclassWhatever.
*/
importcom.sun//MISTAKEImportantnottoputimportstatementhere
publicclassWhatever{
}
AdoccommentiscomposedofamaindescriptionfollowedbyatagsectionThemaindescriptionbeginsafterthestartingdelimiter/**andcontinuesuntilthetagsection.Thetag
sectionstartswiththefirstblocktag,whichisdefinedbythefirst@characterthatbeginsaline(ignoringleadingasterisks,whitespace,andleadingseparator/**).Itispossibletohavea
commentwithonlyatagsectionandnomaindescription.Themaindescriptioncannotcontinueafterthetagsectionbegins.Theargumenttoatagcanspanmultiplelines.Therecanbe
anynumberoftagssometypesoftagscanberepeatedwhileotherscannot.Forexample,this@seestartsthetagsection:
/**
*Thissentencewouldholdthemaindescriptionforthisdoccomment.
*@seejava.lang.Object
*/
BlocktagsandinlinetagsAtagisaspecialkeywordwithinadoccommentthattheJavadoctoolcanprocess.Therearetwokindsoftags:blocktags,whichappearas@tag(alsoknown
as"standalonetags"),andinlinetags,whichappearwithincurlybraces,as{@tag}.Tobeinterpreted,ablocktagmustappearatthebeginningofaline,ignoringleadingasterisks,white
space,andseparator(/**).Thismeansyoucanusethe@characterelsewhereinthetextanditwillnotbeinterpretedasthestartofatag.Ifyouwanttostartalinewiththe@characterand
nothaveitbeinterpreted,usetheHTMLentity&#064.Eachblocktaghasassociatedtext,whichincludesanytextfollowingthetagupto,butnotincluding,eitherthenexttag,ortheendof
thedoccomment.Thisassociatedtextcanspanmultiplelines.Aninlinetagisallowedandinterpretedanywherethattextisallowed.Thefollowingexamplecontainstheblocktag
@deprecatedandinlinetag{@link}.
/**
*@deprecatedAsofJDK1.1,replacedby{@link#setBounds(int,int,int,int)}
*/
CommentsarewritteninHTMLThetextmustbewritteninHTML,inthattheyshoulduseHTMLentitiesandcanuseHTMLtags.YoucanusewhicheverversionofHTMLyourbrowser
supportswehavewrittenthestandarddoclettogenerateHTML3.2compliantcodeelsewhere(outsideofthedocumentationcomments)withtheinclusionofcascadingstylesheetsand
frames.(Weprefaceeachgeneratedfilewith"HTML4.0"becauseoftheframesets.)
Forexample,entitiesforthelessthan(<)andgreaterthan(>)symbolsshouldbewritten&ltand&gt.Likewise,theampersand(&)shouldbewritten&amp.TheboldHTMLtagis
showninthefollowingexample.
Hereisadoccomment:
/**
*Thisisadoccomment.
*@seejava.lang.Object
*/
LeadingasterisksWhenjavadocparsesadoccomment,leadingasterisk(*)charactersoneachlinearediscardedblanksandtabsprecedingtheinitialasterisk(*)charactersarealso
discarded.Startingwith1.4,ifyouomittheleadingasteriskonaline,theleadingwhitespaceisnolongerremoved.Thisenablesyoutopastecodeexamplesdirectlyintoadoccomment
insidea<PRE>tag,anditsindentationwillbehonored.Spacesaregenerallyinterpretedbybrowsersmoreuniformlythantabs.Indentationisrelativetotheleftmargin(ratherthanthe
separator/**or<PRE>tag).
FirstsentenceThefirstsentenceofeachdoccommentshouldbeasummarysentence,containingaconcisebutcompletedescriptionofthedeclaredentity.Thissentenceendsatthefirst
periodthatisfollowedbyablank,tab,orlineterminator,oratthefirstblocktag.TheJavadoctoolcopiesthisfirstsentencetothemembersummaryatthetopoftheHTMLpage.
DeclarationwithmultiplefieldsJavaallowsdeclaringmultiplefieldsinasinglestatement,butthisstatementcanhaveonlyonedocumentationcomment,whichiscopiedforallfields.
Thereforeifyouwantindividualdocumentationcommentsforeachfield,youmustdeclareeachfieldinaseparatestatement.Forexample,thefollowingdocumentationcommentdoesn't
makesensewrittenasasingledeclarationandwouldbebetterhandledastwodeclarations:
/**
*Thehorizontalandverticaldistancesofpoint(x,y)
*/
publicintx,y//Avoidthis
TheJavadoctoolgeneratesthefollowingdocumentationfromtheabovecode:
publicintx
Thehorizontalandverticaldistancesofpoint(x,y)
publicinty
Thehorizontalandverticaldistancesofpoint(x,y)
UseheadertagscarefullyWhenwritingdocumentationcommentsformembers,it'sbestnottouseHTMLheadingtagssuchas<H1>and<H2>,becausetheJavadoctoolcreatesan
entirestructureddocumentandthesestructuraltagsmightinterferewiththeformattingofthegenerateddocument.However,itisfinetousetheseheadingsinclassandpackage
commentstoprovideyourownstructure.
AutomaticCopyingofMethodComments
TheJavadoctoolhastheabilitytocopyor"inherit"methodcommentsinclassesandinterfacesunderthefollowingtwocircumstances.Constructors,fieldsandnestedclassesdonotinherit
doccomments.
AutomaticallyinheritcommenttofillinmissingtextWhenamaindescription,or@return,@paramor@throwstagismissingfromamethodcomment,theJavadoctoolcopiesthe
correspondingmaindescriptionortagcommentfromthemethoditoverridesorimplements(ifany),accordingtothealgorithmbelow.
Morespecifically,whena@paramtagforaparticularparameterismissing,thenthecommentforthatparameteriscopiedfromthemethodfurtheruptheinheritancehierarchy.Whena
@throwstagforaparticularexceptionismissing,the@throwstagiscopiedonlyifthatexceptionisdeclared.
Thisbehaviorcontrastswithversion1.3andearlier,wherethepresenceofanymaindescriptionortagwouldpreventallcommentsfrombeinginherited.
Explicitlyinheritcommentwith{@inheritDoc}tagInserttheinlinetag{@inheritDoc}inamethodmaindescriptionor@return,@paramor@throwstagcommentthe
correspondinginheritedmaindescriptionortagcommentiscopiedintothatspot.
Thesourcefilefortheinheritedmethodneedonlybeonthepathspecifiedbysourcepathforthedoccommenttoactuallybeavailabletocopy.Neithertheclassnoritspackageneedstobe
passedinonthecommandline.Thiscontrastswith1.3.xandearlierreleases,wheretheclasshadtobeadocumentedclass
InheritfromclassesandinterfacesInheritingofcommentsoccursinallthreepossiblecasesofinheritancefromclassesandinterfaces:
Whenamethodinaclassoverridesamethodinasuperclass
Whenamethodinaninterfaceoverridesamethodinasuperinterface
Whenamethodinaclassimplementsamethodinaninterface
Inthefirsttwocases,formethodoverrides,theJavadoctoolgeneratesasubheading"Overrides"inthedocumentationfortheoverridingmethod,withalinktothemethoditisoverriding,
whetherornotthecommentisinherited.
Inthethirdcase,whenamethodinagivenclassimplementsamethodinaninterface,theJavadoctoolgeneratesasubheading"Specifiedby"inthedocumentationfortheoverriding
method,withalinktothemethoditisimplementing.Thishappenswhetherornotthecommentisinherited.
AlgorithmforInheritingMethodCommentsIfamethoddoesnothaveadoccomment,orhasan{@inheritDoc}tag,theJavadoctoolsearchesforanapplicablecommentusingthe
followingalgorithm,whichisdesignedtofindthemostspecificapplicabledoccomment,givingpreferencetointerfacesoversuperclasses:
1.Lookineachdirectlyimplemented(orextended)interfaceintheordertheyappearfollowingthewordimplements(orextends)inthemethoddeclaration.Usethefirstdoccomment
foundforthismethod.
2.Ifstep1failedtofindadoccomment,recursivelyapplythisentirealgorithmtoeachdirectlyimplemented(orextended)interface,inthesameordertheywereexaminedinstep1.
3.Ifstep2failedtofindadoccommentandthisisaclassotherthanObject(notaninterface):
a.Ifthesuperclasshasadoccommentforthismethod,useit.
b.Ifstep3afailedtofindadoccomment,recursivelyapplythisentirealgorithmtothesuperclass.
JAVADOCTAGS
TheJavadoctoolparsesspecialtagswhentheyareembeddedwithinaJavadoccomment.Thesedoctagsenableyoutoautogenerateacomplete,wellformattedAPIfromyoursource
code.Thetagsstartwithan"at"sign(@)andarecasesensitivetheymustbetypedwiththeuppercaseandlowercaselettersasshown.Atagmuststartatthebeginningofaline(afterany
leadingspacesandanoptionalasterisk)oritistreatedasnormaltext.Byconvention,tagswiththesamenamearegroupedtogether.Forexample,putall@seetagstogether.
Tagscomeintwotypes:
BlocktagsCanbeplacedonlyinthetagsectionthatfollowsthemaindescription.Blocktagsareoftheform:@tag.
InlinetagsCanbeplacedanywhereinthemaindescriptionorinthecommentsforblocktags.Inlinetagsaredenotedbycurlybraces:{@tag}.
Thecurrenttagsare:
Tag IntroducedinJDK/SDK
@author 1.0
{@code} 1.5
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
{@literal} 1.5
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0
Forcustomtags,seethetagoption.
@authornametext
Addsan"Author"entrywiththespecifiednametexttothegenerateddocswhentheauthoroptionisused.Adoccommentmaycontainmultiple@authortags.Youcanspecifyone
nameper@authortagormultiplenamespertag.Intheformercase,theJavadoctoolinsertsacomma(,)andspacebetweennames.Inthelattercase,theentiretextissimply
copiedtothegenerateddocumentwithoutbeingparsed.Therefore,youcanusemultiplenamesperlineifyouwantalocalizednameseparatorotherthancomma.
Formoredetails,seeWhereTagsCanBeUsedandwriting@authortags.
@deprecateddeprecatedtext
Note:StartingwithJDK5.0,youcandeprecateaprogramelementusingthe@Deprecatedannotation.AddsacommentindicatingthatthisAPIshouldnolongerbeused(even
thoughitmaycontinuetowork).TheJavadoctoolmovesthedeprecatedtextaheadofthemaindescription,placingitinitalicsandprecedingitwithaboldwarning:"Deprecated".
Thistagisvalidinalldoccomments:overview,package,class,interface,constructor,methodandfield.
ThefirstsentenceofdeprecatedtextshouldatleasttelltheuserwhentheAPIwasdeprecatedandwhattouseasareplacement.TheJavadoctoolcopiesjustthefirstsentenceto
thesummarysectionandindex.Subsequentsentencescanalsoexplainwhyithasbeendeprecated.Youshouldincludea{@link}tag(forJavadoc1.2orlater)thatpointstothe
replacementAPI:
Formoredetails,seewriting@deprecatedtags.
ForJavadoc1.2andlater,usea{@link}tag.Thiscreatesthelinkinline,whereyouwantit.Forexample:
/**
*@deprecatedAsofJDK1.1,replacedby{@link#setBounds(int,int,int,int)}
*/
ForJavadoc1.1,thestandardformatistocreatea@seetag(whichcannotbeinline)foreach@deprecatedtag.
Formoreaboutdeprecation,seeThe@deprecatedtag.
{@codetext}
Equivalentto<code>{@literal}</code>.
DisplaystextincodefontwithoutinterpretingthetextasHTMLmarkupornestedjavadoctags.Thisenablesyoutouseregularanglebrackets(<and>)insteadoftheHTMLentities
(&ltand&gt)indoccomments,suchasinparametertypes(<Object>),inequalities(3<4),orarrows(<).Forexample,thedoccommenttext:
{@codeAC}
displaysinthegeneratedHTMLpageunchanged,as:
AC
Thenoteworthypointisthattheisnotinterpretedasboldandisincodefont.
Ifyouwantthesamefunctionalitywithoutthecodefont,use{@literal}.
{@docRoot}
Representstherelativepathtothegenerateddocument's(destination)rootdirectoryfromanygeneratedpage.Itisusefulwhenyouwanttoincludeafile,suchasacopyrightpageor
companylogo,thatyouwanttoreferencefromallgeneratedpages.Linkingtothecopyrightpagefromthebottomofeachpageiscommon.
This{@docRoot}tagcanbeusedbothonthecommandlineandinadoccomment:Thistagisvalidinalldoccomments:overview,package,class,interface,constructor,method
andfield,includingthetextportionofanytag(suchas@return,@paramand@deprecated).
1.Onthecommandline,wheretheheader/footer/bottomaredefined:
javadocbottom'<ahref="{@docRoot}/copyright.html">Copyright</a>'
NOTEWhenusing{@docRoot}thiswayinamakefile,somemakefileprogramsrequirespecialescapingforthebrace{}characters.Forexample,theInpriseMAKEversion
5.2runningonWindowsrequiresdoublebraces:{{@docRoot}}.Italsorequiresdouble(ratherthansingle)quotestoencloseargumentstooptionssuchasbottom(withthe
quotesaroundthehrefargumentomitted).
2.Inadoccomment:
/**
*Seethe<ahref="{@docRoot}/copyright.html">Copyright</a>.
*/
Thereasonthistagisneededisbecausethegenerateddocsareinhierarchicaldirectories,asdeepasthenumberofsubpackages.Thisexpression:
<ahref="{@docRoot}/copyright.html">
wouldresolveto:
<ahref="../../copyright.html">forjava/lang/Object.java
and
<ahref="../../../copyright.html">forjava/lang/ref/Reference.java
@exceptionclassnamedescription
The@exceptiontagisasynonymfor@throws.
{@inheritDoc}
Inherits(copies)documentationfromthe"nearest"inheritableclassorimplementableinterfaceintothecurrentdoccommentatthistag'slocation.Thisallowsyoutowritemore
generalcommentshigheruptheinheritancetree,andtowritearoundthecopiedtext.
Thistagisvalidonlyintheseplacesinadoccomment:
Inthemaindescriptionblockofamethod.Inthiscase,themaindescriptioniscopiedfromaclassorinterfaceupthehierarchy.
Inthetextargumentsofthe@return,@paramand@throwstagsofamethod.Inthiscase,thetagtextiscopiedfromthecorrespondingtagupthehierarchy.
SeeAutomaticCopyingofMethodCommentsforamoreprecisedescriptionofhowcommentsarefoundintheinheritancehierarchy.Notethatifthistagismissing,thecommentis
orisnotautomaticallyinheritedaccordingtorulesdescribedinthatsection.
{@linkpackage.class#memberlabel}
Insertsaninlinelinkwithvisibletextlab elthatpointstothedocumentationforthespecifiedpackage,classormembernameofareferencedclass.Thistagisvalidinalldoc
comments:overview,package,class,interface,constructor,methodandfield,includingthetextportionofanytag(suchas@return,@paramand@deprecated).
Thistagisverysimliarto@seebothrequirethesamereferencesandacceptexactlythesamesyntaxforpackage.class#memb erandlab el.Themaindifferenceisthat{@link}
generatesaninlinelinkratherthanplacingthelinkinthe"SeeAlso"section.Also,the{@link}tagbeginsandendswithcurlybracestoseparateitfromtherestoftheinlinetext.If
youneedtouse"}"insidethelabel,usetheHTMLentitynotation&#125
Thereisnolimittothenumberof{@link}tagsallowedinasentence.Youcanusethistaginthemaindescriptionpartofanydocumentationcommentorinthetextportionofanytag
(suchas@deprecated,@returnor@param).
Forexample,hereisacommentthatreferstothegetComponentAt(int,int)method:
Usethe{@link#getComponentAt(int,int)getComponentAt}method.
Fromthis,thestandarddocletwouldgeneratethefollowingHTML(assumingitreferstoanotherclassinthesamepackage):
Usethe<ahref="Component.html#getComponentAt(int,int)">getComponentAt</a>method.
Whichappearsonthewebpageas:
UsethegetComponentAtmethod.
Youcanextend{@link}tolinktoclassesnotbeingdocumentedbyusingthelinkoption.
Formoredetails,seewriting{@link}tags.
{@linkplainpackage.class#memberlabel}
Identicalto{@link},exceptthelink'slabelisdisplayedinplaintextthancodefont.Usefulwhenthelabelisplaintext.Example:
Referto{@linkplainadd()theoverriddenmethod}.
Thiswoulddisplayas:
Refertotheoverriddenmethod.
{@literaltext}
DisplaystextwithoutinterpretingthetextasHTMLmarkupornestedjavadoctags.Thisenablesyoutouseregularanglebrackets(<and>)insteadoftheHTMLentities(&ltand
&gt)indoccomments,suchasinparametertypes(<Object>),inequalities(3<4),orarrows(<).Forexample,thedoccommenttext:
{@literalAC}
displaysunchangedinthegeneratedHTMLpageinyourbrowser,as:
AC
Thenoteworthypointisthattheisnotinterpretedasbold(anditisnotincodefont).
Ifyouwantthesamefunctionalitybutwiththetextincodefont,use{@code}.
@paramparameternamedescription
Addsaparameterwiththespecifiedparameternamefollowedbythespecifieddescriptiontothe"Parameters"section.Whenwritingthedoccomment,youmaycontinuethe
descriptionontomultiplelines.Thistagisvalidonlyinadoccommentforamethod,constructororclass.
Theparameternamecanbethenameofaparameterinamethodorconstructor,orthenameofatypeparameterofaclass,methodorconstructor.Useanglebracketsaroundthis
parameternametospecifytheuseofatypeparameter.
Exampleofatypeparameterofaclass:
/**
*@param<E>Typeofelementstoredinalist
*/
publicinterfaceList<E>extendsCollection<E>{
}
Exampleofatypeparameterofamethod:
/**
*@paramstringthestringtobeconverted
*@paramtypethetypetoconvertthestringto
*@param<T>thetypeoftheelement
*@param<V>thevalueoftheelement
*/
<T,VextendsT>Vconvert(Stringstring,Class<T>type){
}
Formoredetails,seewriting@paramtags.
@returndescription
Addsa"Returns"sectionwiththedescriptiontext.Thistextshoulddescribethereturntypeandpermissiblerangeofvalues.Thistagisvalidonlyinadoccommentforamethod.
Formoredetails,seewriting@returntags.
@seereference
Addsa"SeeAlso"headingwithalinkortextentrythatpointstoreference.Adoccommentmaycontainanynumberof@seetags,whichareallgroupedunderthesameheading.The
@seetaghasthreevariationsthethirdformbelowisthemostcommon.Thistagisvalidinanydoccomment:overview,package,class,interface,constructor,methodorfield.For
insertinganinlinelinkwithinasentencetoapackage,classormember,see{@link}.
@see"string"
Addsatextentryforstring.Nolinkisgenerated.ThestringisabookorotherreferencetoinformationnotavailablebyURL.TheJavadoctooldistinguishesthisfromthe
previouscasesbylookingforadoublequote(")asthefirstcharacter.Forexample:
@see"TheJavaProgrammingLanguage"
Thisgeneratestextsuchas:
SeeAlso:
"TheJavaProgrammingLanguage"
@see<ahref="URL#value">label</a>
AddsalinkasdefinedbyURL#value.TheURL#valueisarelativeorabsoluteURL.TheJavadoctooldistinguishesthisfromothercasesbylookingforalessthansymbol(<)
asthefirstcharacter.Forexample:
@see<ahref="spec.html#section">JavaSpec</a>
Thisgeneratesalinksuchas:
SeeAlso:
JavaSpec
@seepackage.class#memberlabel
Addsalink,withvisibletextlab el,thatpointstothedocumentationforthespecifiednameintheJavaLanguagethatisreferenced.Thelab elisoptionalifomitted,thename
appearsinsteadasthevisibletext,suitablyshortenedseeHowanameisdisplayed.Usenoqualifiertogloballyremovethepackagenamefromthisvisibletext.Usethe
labelwhenyouwantthevisibletexttobedifferentfromtheautogeneratedvisibletext.
Onlyinversion1.2,justthenamebutnotthelabelwouldautomaticallyappearin<code>HTMLtags,Startingwith1.2.2,the<code>isalwaysincludedaroundthevisibletext,
whetherornotalabelisused.
package.class#memberisanyvalidprogramelementnamethatisreferencedapackage,class,interface,constructor,methodorfieldnameexceptthatthe
characteraheadofthemembernameshouldbeahashcharacter(#).Theclassrepresentsanytoplevelornestedclassorinterface.Thememb errepresentsany
constructor,methodorfield(notanestedclassorinterface).Ifthisnameisinthedocumentedclasses,theJavadoctoolwillautomaticallycreatealinktoit.Tocreate
linkstoexternalreferencedclasses,usethelinkoption.Useeitheroftheothertwo@seeformsforreferringtodocumentationofanamethatdoesnotbelongtoa
referencedclass.ThisargumentisdescribedatgreaterlengthbelowunderSpecifyingaName.
labelisoptionaltextthatisvisibleasthelink'slabel.Thelab elcancontainwhitespace.Iflab elisomitted,thenpackage.class.memb erwillappear,suitablyshortened
relativetothecurrentclassandpackageseeHowanameisdisplayed.
Aspaceisthedelimiterbetweenpackage.class#memb erandlab el.Aspaceinsideparenthesesdoesnotindicatethestartofalabel,sospacesmaybeusedbetween
parametersinamethod.
ExampleInthisexample,an@seetag(intheCharacterclass)referstotheequalsmethodintheStringclass.Thetagincludesbotharguments:thename
"String#equals(Object)"andthelabel"equals".
/**
*@seeString#equals(Object)equals
*/
ThestandarddocletproducesHTMLsomethinglikethis:
<dl>
<dt>SeeAlso:
<dd><ahref="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
</dl>
Whichlookssomethinglikethisinabrowser,wherethelabelisthevisiblelinktext:
SeeAlso:
equals
SpecifyinganameThispackage.class#memb ernamecanbeeitherfullyqualified,suchasjava.lang.String#toUpperCase()ornot,suchasString#toUpperCase()
or#toUpperCase().Iflessthanfullyqualified,theJavadoctoolusesthenormalJavacompilersearchordertofindit,furtherdescribedbelowinSearchorderfor@see.The
namecancontainwhitespacewithinparentheses,suchasbetweenmethodarguments.
Ofcoursetheadvantageofprovidingshorter,"partiallyqualified"namesisthattheyareshortertotypeandthereislessclutterinthesourcecode.Thefollowingtableshows
thedifferentformsofthename,whereClasscanbeaclassorinterface,Typecanbeaclass,interface,array,orprimitive,andmethodcanbeamethodorconstructor.
Typicalformsfor@seepackage.class#member
Referencingamemberofthecurrentclass
@see#field
@see#method(Type,Type,...)
@see#method(Typeargname,Typeargname,...)
@see#constructor(Type,Type,...)
@see#constructor(Typeargname,Typeargname,...)
Referencinganotherclassinthecurrentorimportedpackages
@seeClass#field
@seeClass#method(Type,Type,...)
@seeClass#method(Typeargname,Typeargname,...)
@seeClass#constructor(Type,Type,...)
@seeClass#constructor(Typeargname,Typeargname,...)
@seeClass.NestedClass
@seeClass
Referencinganelementinanotherpackage(fullyqualified)
@seepackage.Class#field
@seepackage.Class#method(Type,Type,...)
@seepackage.Class#method(Typeargname,Typeargname,...)
@seepackage.Class#constructor(Type,Type,...)
@seepackage.Class#constructor(Typeargname,Typeargname,...)
@seepackage.Class.NestedClass
@seepackage.Class
@seepackage
Thefollowingnotesapplytotheabovetable:
Thefirstsetofforms(withnoclassorpackage)willcausetheJavadoctooltosearchonlythroughthecurrentclass'shierarchy.Itwillfindamemberofthecurrentclass
orinterface,oneofitssuperclassesorsuperinterfaces,oroneofitsenclosingclassesorinterfaces(searchsteps13).Itwillnotsearchtherestofthecurrentpackageor
otherpackages(searchsteps45).
Ifanymethodorconstructorisenteredasanamewithnoparentheses,suchasgetValue,andifthereisnofieldwiththesamename,theJavadoctoolwillcorrectly
createalinktoit,butwillprintawarningmessageremindingyoutoaddtheparenthesesandarguments.Ifthismethodisoverloaded,theJavadoctoolwilllinktothefirst
methoditssearchencounters,whichisunspecified.
Nestedclassesmustbespecifiedasouter.inner,notsimplyinner,forallforms.
Asstated,thehashcharacter(#),ratherthanadot(.)separatesamemberfromitsclass.ThisenablestheJavadoctooltoresolveambiguities,sincethedotalso
separatesclasses,nestedclasses,packages,andsubpackages.However,theJavadoctoolisgenerallylenientandwillproperlyparseadotifyouknowthereisno
ambiguity,thoughitwillprintawarning.
Searchorderfor@seetheJavadoctoolwillprocessa@seetagthatappearsinasourcefile(.java),packagefile(package.htmlorpackageinfo.java)oroverviewfile
(overview.html).Inthelattertwofiles,youmustfullyqualifythenameyousupplywith@see.Inasourcefile,youcanspecifyanamethatisfullyqualifiedorpartiallyqualified.
WhentheJavadoctoolencountersa@seetagina.javafilethatisnotfullyqualified,itsearchesforthespecifiednameinthesameorderastheJavacompilerwould(except
theJavadoctoolwillnotdetectcertainnamespaceambiguities,sinceitassumesthesourcecodeisfreeoftheseerrors).ThissearchorderisformallydefinedintheJava
LanguageSpecification.TheJavadoctoolsearchesforthatnamethroughallrelatedandimportedclassesandpackages.Inparticular,itsearchesinthisorder:
1.thecurrentclassorinterface
2.anyenclosingclassesandinterfaces,searchingclosestfirst
3.anysuperclassesandsuperinterfaces,searchingclosestfirst
4.thecurrentpackage
5.anyimportedpackages,classesandinterfaces,searchingintheorderoftheimportstatement
TheJavadoctoolcontinuestosearchrecursivelythroughsteps13foreachclassitencountersuntilitfindsamatch.Thatis,afteritsearchesthroughthecurrentclassandits
enclosingclassE,itwillsearchthroughE'ssuperclassesbeforeE'senclosingclasses.Insteps4and5,theJavadoctooldoesnotsearchclassesorinterfaceswithina
packageinanyspecifiedorder(thatorderdependsontheparticularcompiler).Instep5,theJavadoctoollooksinjava.lang,sincethatisautomaticallyimportedbyall
programs.
TheJavadoctooldoesnotnecessarilylookinsubclasses,norwillitlookinotherpackageseveniftheirdocumentationisbeinggeneratedinthesamerun.Forexample,ifthe
@seetagisinthejava.awt.event.KeyEventclassandreferstoanameinthejava.awtpackage,javadocdoesnotlookinthatpackageunlessthatclassimportsit.
HowanameisdisplayedIflab elisomitted,thenpackage.class.memb erappears.Ingeneral,itissuitablyshortenedrelativetothecurrentclassandpackage.By

"shortened",wemeantheJavadoctooldisplaysonlytheminimumnamenecessary.Forexample,iftheString.toUpperCase()methodcontainsreferencestoamemberof
thesameclassandtoamemberofadifferentclass,theclassnameisdisplayedonlyinthelattercase,asshowninthefollowingtable.
Usenoqualifiertogloballyremovethepackagenames.
TypeofReference ExampleinString.toUpperCase() DisplaysAs
@seetagreferstomemberofthesameclass,samepackage @seeString#toLowerCase() toLowerCase()

(omitsthepackageandclassnames)
@seetagreferstomemberofadifferentclass,samepackage @seeCharacter#toLowerCase(char) Character.toLowerCase(char)

(omitsthepackagename,includestheclassname)
@seetagreferstomemberofadifferentclass,differentpackage @seejava.io.File#exists() java.io.File.exists()

(includesthepackageandclassnames)
Examplesof@see
Thecommenttotherightshowshowthenamewouldbedisplayedifthe@seetagisinaclassinanotherpackage,suchasjava.applet.Applet.
Seealso:
@seejava.lang.String//String
@seejava.lang.StringTheStringclass//TheStringclass
@seeString//String
@seeString#equals(Object)//String.equals(Object)
@seeString#equals//String.equals(java.lang.Object)
@seejava.lang.Object#wait(long)//java.lang.Object.wait(long)
@seeCharacter#MAX_RADIX//Character.MAX_RADIX
@see<ahref="spec.html">JavaSpec</a>//JavaSpec
@see"TheJavaProgrammingLanguage"//"TheJavaProgrammingLanguage"
Youcanextend@seetolinktoclassesnotbeingdocumentedbyusingthelinkoption.
Formoredetails,seewriting@seetags.
@serialfielddescription|include|exclude
Usedinthedoccommentforadefaultserializablefield.
Anoptionalfielddescriptionshouldexplainthemeaningofthefieldandlisttheacceptablevalues.Ifneeded,thedescriptioncanspanmultiplelines.Thestandarddocletaddsthis
informationtotheserializedformpage.
Ifaserializablefieldwasaddedtoaclasssometimeaftertheclasswasmadeserializable,astatementshouldbeaddedtoitsmaindescriptiontoidentifyatwhichversionitwas
added.
Theincludeandexcludeargumentsidentifywhetheraclassorpackageshouldbeincludedorexcludedfromtheserializedformpage.Theyworkasfollows:
ApublicorprotectedclassthatimplementsSerializableisincludedunlessthatclass(oritspackage)ismarked@serialexclude.
AprivateorpackageprivateclassthatimplementsSerializableisexcludedunlessthatclass(oritspackage)ismarked@serialinclude.
Examples:Thejavax.swingpackageismarked@serialexclude(inpackage.htmlorpackageinfo.java).Thepublicclassjava.security.BasicPermissionismarked
@serialexclude.Thepackageprivateclassjava.util.PropertyPermissionCollectionismarked@serialinclude.
Thetag@serialataclassleveloverrides@serialatapackagelevel.
Formoreinformationabouthowtousethesetags,alongwithanexample,see"DocumentingSerializableFieldsandDataforaClass,"Section1.6oftheJavaOb jectSerialization
Specification.AlsoseetheSerializationFAQ,whichcoverscommonquestions,suchas"WhydoIseejavadocwarningsstatingthatIammissing@serialtagsforprivatefieldsifIam
notrunningjavadocwiththeprivateswitch?".AlsoseeOracle'scriteriaforincludingclassesintheserializedformspecification.
@serialFieldfieldnamefieldtypefielddescription
DocumentsanObjectStreamFieldcomponentofaSerializableclass'sserialPersistentFieldsmember.One@serialFieldtagshouldbeusedforeach
ObjectStreamFieldcomponent.
@serialDatadatadescription
Thedatadescriptiondocumentsthetypesandorderofdataintheserializedform.Specifically,thisdataincludestheoptionaldatawrittenbythewriteObjectmethodandalldata
(includingbaseclasses)writtenbytheExternalizable.writeExternalmethod.
The@serialDatatagcanbeusedinthedoccommentforthewriteObject,readObject,writeExternal,readExternal,writeReplace,andreadResolvemethods.
@sincesincetext
Addsa"Since"headingwiththespecifiedsincetexttothegenerateddocumentation.Thetexthasnospecialinternalstructure.Thistagisvalidinanydoccomment:overview,
package,class,interface,constructor,methodorfield.Thistagmeansthatthischangeorfeaturehasexistedsincethesoftwarereleasespecifiedbythesincetext.Forexample:
@since1.5
ForsourcecodeintheJavaplatform,thistagindicatestheversionoftheJavaplatformAPIspecification(notnecessarilywhenitwasaddedtothereferenceimplementation).Multiple
@sincetagsareallowedandaretreatedlikemultiple@authortags.YoucouldusemultipletagsiftheprgramelementisusedbymorethanoneAPI.
@throwsclassnamedescription
The@throwsand@exceptiontagsaresynonyms.Addsa"Throws"subheadingtothegenerateddocumentation,withtheclassnameanddescriptiontext.Theclassnameisthe
nameoftheexceptionthatmaybethrownbythemethod.Thistagisvalidonlyinthedoccommentforamethodorconstructor.Ifthisclassisnotfullyspecified,theJavadoctooluses
thesearchordertolookupthisclass.Multiple@throwstagscanbeusedinagivendoccommentforthesameordifferentexceptions.
Toensurethatallcheckedexceptionsaredocumented,ifa@throwstagdoesnotexistforanexceptioninthethrowsclause,theJavadoctoolautomaticallyaddsthatexceptiontothe
HTMLoutput(withnodescription)asifitweredocumentedwith@throwstag.
The@throwsdocumentationiscopiedfromanoverriddenmethodtoasubclassonlywhentheexceptionisexplicitlydeclaredintheoverriddenmethod.Thesameistrueforcopying
fromaninterfacemethodtoanimplementingmethod.Youcanuse{@inheritDoc}toforce@throwstoinheritdocumentation.
Formoredetails,seewriting@throwstags.
{@valuepackage.class#field}
When{@value}isused(withoutanyargument)inthedoccommentofastaticfield,itdisplaysthevalueofthatconstant:
/**
*Thevalueofthisconstantis{@value}.
*/
publicstaticfinalStringSCRIPT_START="<script>"
Whenusedwithargumentpackage.class#fieldinanydoccomment,itdisplaysthevalueofthespecifiedconstant:
/**
*Evaluatesthescriptstartingwith{@value#SCRIPT_START}.
*/
publicStringevalScript(Stringscript){
}
Theargumentpackage.class#fieldtakesaformidenticaltothatofthe@seeargument,exceptthatthemembermustbeastaticfield.
ThesevaluesoftheseconstantsarealsodisplayedontheConstantFieldValuespage.
@versionversiontext
Addsa"Version"subheadingwiththespecifiedversiontexttothegenerateddocswhentheversionoptionisused.Thistagisintendedtoholdthecurrentversionnumberofthe
softwarethatthiscodeispartof(asopposedto@since,whichholdstheversionnumberwherethiscodewasintroduced).Theversiontexthasnospecialinternalstructure.Tosee
wheretheversiontagcanbeused,seeWhereTagsCanBeUsed.
Adoccommentmaycontainmultiple@versiontags.Ifitmakessense,youcanspecifyoneversionnumberper@versiontagormultipleversionnumberspertag.Intheformer
case,theJavadoctoolinsertsacomma(,)andspacebetweennames.Inthelattercase,theentiretextissimplycopiedtothegenerateddocumentwithoutbeingparsed.Therefore,
youcanusemultiplenamesperlineifyouwantalocalizednameseparatorotherthancomma.
Formoredetails,seewriting@versiontags.
WhereTagsCanBeUsed
Thefollowingsectionsdescribewherethetagscanbeused.Notethatthesetagscanbeusedinalldoccomments:@see,@since,@deprecated,{@link},{@linkplain},and
{@docroot}.
OverviewDocumentationTags
Overviewtagsaretagsthatcanappearinthedocumentationcommentfortheoverviewpage(whichresidesinthesourcefiletypicallynamedoverview.html).Likeinanyother
documentationcomments,thesetagsmustappearafterthemaindescription.
NOTEThe{@link}taghasabuginoverviewdocumentsinversion1.2thetextappearsproperlybuthasnolink.The{@docRoot}tagdoesnotcurrentlyworkinoverviewdocuments.
OverviewTags
@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}
PackageDocumentationTags
Packagetagsaretagsthatcanappearinthedocumentationcommentforapackage(whichresidesinthesourcefilenamedpackage.htmlorpackageinfo.java).The@serialtagcan
onlybeusedherewiththeincludeorexcludeargument.
PackageTags
@see
@since
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}
ClassandInterfaceDocumentationTags
Thefollowingaretagsthatcanappearinthedocumentationcommentforaclassorinterface.The@serialtagcanonlybeusedherewiththeincludeorexcludeargument.
Class/InterfaceTags
@see
@since
@deprecated
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}
Anexampleofaclasscomment:
/**
*Aclassrepresentingawindowonthescreen.
*Forexample:
*<pre>
*Windowwin=newWindow(parent)
*win.show()
*</pre>
*
*@authorSamiShaio
*@version1.15,13Dec2006
*@seejava.awt.BaseWindow
*@seejava.awt.Button
*/
classWindowextendsBaseWindow{
...
}
FieldDocumentationTags
Thefollowingarethetagsthatcanappearinthedocumentationcommentforafield.
FieldTags
@see
@since
@deprecated
@serial
@serialField
{@link}
{@linkplain}
{@docRoot}
{@value}
Anexampleofafieldcomment:
/**
*TheXcoordinateofthecomponent.
*
*@see#getLocation()
*/
intx=1263732
ConstructorandMethodDocumentationTags
Thefollowingarethetagsthatcanappearinthedocumentationcommentforaconstructorormethod,exceptfor@return,whichcannotappearinaconstructor,and{@inheritDoc},which
hascertainrestrictions.The@serialDatatagcanonlybeusedinthedoccommentforcertainserializationmethods.
Method/ConstructorTags
@see
@since
@deprecated
@param
@return
@throwsand@exception
@serialData
{@link}
{@linkplain}
{@inheritDoc}
{@docRoot}
Anexampleofamethoddoccomment:
/**
*Returnsthecharacteratthespecifiedindex.Anindex
*rangesfrom<code>0</code>to<code>length()1</code>.
*
*@paramindextheindexofthedesiredcharacter.
*@returnthedesiredcharacter.
*@exceptionStringIndexOutOfRangeException
*iftheindexisnotintherange<code>0</code>
*to<code>length()1</code>.
*@seejava.lang.Character#charValue()
*/
publiccharcharAt(intindex){
...
}
OPTIONS
Thejavadoctoolusesdocletstodetermineitsoutput.TheJavadoctoolusesthedefaultstandarddocletunlessacustomdocletisspecifiedwiththedocletoption.TheJavadoctool
providesasetofcommandlineoptionsthatcanbeusedwithanydoclettheseoptionsaredescribedbelowunderthesubheadingJavadocOptions.Thestandarddocletprovidesan
additionalsetofcommandlineoptionsthataredescribedbelowunderthesubheadingOptionsProvidedbytheStandardDoclet.Alloptionnamesarecaseinsensitive,thoughtheir
argumentscanbecasesensitive.
Theoptionsare:
1.1 header private

author help protected
b ootclasspath helpfile pub lic
bottom J quiet
b reakiterator keywords serialwarn
charset link source
classpath linkoffline sourcepath
d linksource sourcetab
docencoding locale splitindex
docfilessubdirs nocomment stylesheetfile
doclet nodeprecated sub packages
docletpath nodeprecatedlist tag
doctitle nohelp taglet
encoding noindex tagletpath
exclude nonavbar title
excludedocfilessubdir noqualifier top
extdirs nosince use
footer notimestamp verb ose
group notree version
overview windowtitle
package
OptionsshowninitalicaretheJavadoccoreoptions,whichareprovidedbythefrontendoftheJavadoctoolandareavailabletoalldoclets.Thestandarddocletitselfprovidesthenonitalic
options.
JavadocOptions
overviewpath\filename
Specifiesthatjavadocshouldretrievethetextfortheoverviewdocumentationfromthe"source"filespecifiedbypath/filenameandplaceitontheOverviewpage(overview
summary.html).Thepath/filenameisrelativetothecurrentdirectory.
Whileyoucanuseanynameyouwantforfilenameandplaceitanywhereyouwantforpath,atypicalthingtodoistonameitoverview.htmlandplaceitinthesourcetreeatthe
directorythatcontainsthetopmostpackagedirectories.Inthislocation,nopathisneededwhendocumentingpackages,sincesourcepathwillpointtothisfile.Forexample,ifthe
sourcetreeforthejava.langpackageisC:\src\classes\java\lang\,thenyoucouldplacetheoverviewfileatC:\src\classes\overview.html.SeeRealWorldExample.
Forinformationaboutthefilespecifiedbypath/filename,seeoverviewcommentfile.
Notethattheoverviewpageiscreatedonlyifyoupassintojavadoctwoormorepackagenames.Forfurtherexplanation,seeHTMLFrames.)
Thetitleontheoverviewpageissetbydoctitle.
public
Showsonlypublicclassesandmembers.
protected
Showsonlyprotectedandpublicclassesandmembers.Thisisthedefault.
package
Showsonlypackage,protected,andpublicclassesandmembers.
private
Showsallclassesandmembers.
help
Displaystheonlinehelp,whichliststhesejavadocanddocletcommandlineoptions.
docletclass
Specifiestheclassfilethatstartsthedocletusedingeneratingthedocumentation.Usethefullyqualifiedname.Thisdocletdefinesthecontentandformatstheoutput.Ifthedoclet
optionisnotused,javadocusesthestandarddocletforgeneratingthedefaultHTMLformat.Thisclassmustcontainthestart(Root)method.Thepathtothisstartingclassis
definedbythedocletpathoption.
SeeDocletOverviewformoreinformation.
docletpathclasspathlist
Specifiesthepathtothedocletstartingclassfile(specifiedwiththedocletoption)andanyjarfilesitdependson.Ifthestartingclassfileisinajarfile,thenthisspecifiesthepath
tothatjarfile,asshownintheexamplebelow.Youcanspecifyanabsolutepathorapathrelativetothecurrentdirectory.Ifclasspathlistcontainsmultiplepathsorjarfiles,theyshould
beseparatedwithacolon(:)onSolarisandasemicolon()onWindows.Thisoptionisnotnecessaryifthedocletstartingclassisalreadyinthesearchpath.
SeeDocletOverviewformoreinformation.
1.1
Thisfeaturehasb eenremovedfromJavadoc1.4.Thereisnoreplacementforit.Thisoptioncreateddocumentationwiththeappearanceandfunctionalityofdocumentationgenerated
b yJavadoc1.1(itneversupportednestedclasses).Ifyouneedthisoption,useJavadoc1.2or1.3instead.
sourcerelease
Specifiestheversionofsourcecodeaccepted.Thefollowingvaluesforreleaseareallowed:
Release
Notes
Value
1.5 javadocacceptscodecontaininggenericsandotherlanguagefeaturesintroducedinJDK1.5.Thecompilerdefaultstothe1.5behaviorifthesourceflagisnotused.
1.4 javadocacceptscodecontainingassertions,whichwereintroducedinJDK1.4.
1.3 javadocdoesnotsupportassertions,generics,orotherlanguagefeaturesintroducedafterJDK1.3.
Usethevalueofreleasecorrespondingtothatusedwhencompilingthecodewithjavac.
sourcepathsourcepathlist
Specifiesthesearchpathsforfindingsourcefiles(.java)whenpassingpackagenamesorsubpackagesintothejavadoccommand.Thesourcepathlistcancontainmultiple
pathsbyseparatingthemwithasemicolon().TheJavadoctoolwillsearchinallsubdirectoriesofthespecifiedpaths.Notethatthisoptionisnotonlyusedtolocatethesourcefiles
beingdocumented,butalsotofindsourcefilesthatarenotbeingdocumentedbutwhosecommentsareinheritedbythesourcefilesbeingdocumented.
Notethatyoucanusethesourcepathoptiononlywhenpassingpackagenamesintothejavadoccommanditwillnotlocate.javafilespassedintothejavadoccommand.(To
locate.javafiles,cdtothatdirectoryorincludethepathaheadofeachfile,asshownatDocumentingOneorMoreClasses.)Ifsourcepathisomitted,javadocusestheclasspath
tofindthesourcefiles(seeclasspath).Therefore,thedefaultsourcepathisthevalueofclasspath.Ifclasspathisomittedandyouarepassingpackagenamesintojavadoc,it
looksinthecurrentdirectory(andsubdirectories)forthesourcefiles.
Setsourcepathlisttotherootdirectoryofthesourcetreeforthepackageyouaredocumenting.Forexample,supposeyouwanttodocumentapackagecalledcom.mypackagewhose
sourcefilesarelocatedat:
C:\user\src\com\mypackage\*.java
InthiscaseyouwouldspecifythesourcepathtoC:\user\src,thedirectorythatcontainscom\mypackage,andthensupplythepackagenamecom.mypackage:
C:>javadocsourcepathC:\user\srccom.mypackage
Thisiseasytorememberbynoticingthatifyouconcatenatethevalueofsourcepathandthepackagenametogetherandchangethedottoabackslash"\",youendupwiththefull
pathtothepackage:C:\user\src\com\mypackage.
Topointtotwosourcepaths:
C:>javadocsourcepathC:\user1\srcC:\user2\srccom.mypackage
classpathclasspathlist
Specifiesthepathswherejavadocwilllookforreferencedclasses(.classfiles)thesearethedocumentedclassesplusanyclassesreferencedbythoseclasses.The
classpathlistcancontainmultiplepathsbyseparatingthemwithasemicolon().TheJavadoctoolwillsearchinallsubdirectoriesofthespecifiedpaths.Followtheinstructionsin
classpathdocumentationforspecifyingclasspathlist.
Ifsourcepathisomitted,theJavadoctoolusesclasspathtofindthesourcefilesaswellasclassfiles(forbackwardcompatibility).Therefore,ifyouwanttosearchforsource
andclassfilesinseparatepaths,usebothsourcepathandclasspath.
Forexample,ifyouwanttodocumentcom.mypackage,whosesourcefilesresideinthedirectoryC:\user\src\com\mypackage,andifthispackagereliesonalibraryin
C:\user\lib,youwouldspecify:
C:>javadocclasspath\user\libsourcepath\user\srccom.mypackage
Aswithothertools,ifyoudonotspecifyclasspath,theJavadoctoolusestheCLASSPATHenvironmentvariable,ifitisset.Ifbotharenotset,theJavadoctoolsearchesforclasses
fromthecurrentdirectory.
ForanindepthdescriptionofhowtheJavadoctoolusesclasspathtofinduserclassesasitrelatestoextensionclassesandbootstrapclasses,seeHowClassesAreFound.
Asaspecialconvenience,aclasspathelementcontainingabasenameof*isconsideredequivalenttospecifyingalistofallthefilesinthedirectorywiththeextension.jaror.JAR
(ajavaprogramcannottellthedifferencebetweenthetwoinvocations).
Forexample,ifdirectoryfoocontainsa.jarandb.JAR,thentheclasspathelementfoo/*isexpandedtoaA.jar:b.JAR,exceptthattheorderofjarfilesisunspecified.Alljarfiles
inthespecifieddirectory,evenhiddenones,areincludedinthelist.Aclasspathentryconsistingsimplyof*expandstoalistofallthejarfilesinthecurrentdirectory.TheCLASSPATH
environmentvariable,wheredefined,willbesimilarlyexpanded.AnyclasspathwildcardexpansionoccursbeforetheJavavirtualmachineisstartednoJavaprogramwilleversee
unexpandedwildcardsexceptbyqueryingtheenvironment.ForexamplebyinvokingSystem.getenv("CLASSPATH").
subpackagespackage1:package2:...
Generatesdocumentationfromsourcefilesinthespecifiedpackagesandrecursivelyintheirsubpackages.Thisoptionisusefulwhenaddingnewsubpackagestothesourcecode,
astheyareautomaticallyincluded.Eachpackageargumentisanytoplevelsubpackage(suchasjava)orfullyqualifiedpackage(suchasjavax.swing)thatdoesnotneedto
containsourcefiles.Argumentsareseparatedbycolons(onalloperatingsystmes).Wildcardsarenotneededorallowed.Usesourcepathtospecifywheretofindthepackages.
Thisoptionissmartaboutnotprocessingsourcefilesthatareinthesourcetreebutdonotbelongtothepackages,asdescribedatprocessingofsourcefiles.
Forexample:
C:>javadocddocssourcepathC:\user\srcsubpackagesjava:javax.swing
Thiscommandgeneratesdocumentationforpackagesnamed"java"and"javax.swing"andalltheirsubpackages.
Youcanusesubpackagesinconjunctionwithexcludetoexcludespecificpackages.
excludepackagename1:packagename2:...
Unconditionallyexcludesthespecifiedpackagesandtheirsubpackagesfromthelistformedbysubpackages.Itexcludesthosepackageseveniftheywouldotherwisebeincluded
bysomepreviousorlatersubpackagesoption.Forexample:
C:>javadocsourcepathC:\user\srcsubpackagesjavaexcludejava.net:java.lang
wouldincludejava.io,java.util,andjava.math(amongothers),butwouldexcludepackagesrootedatjava.netandjava.lang.Noticethisexcludesjava.lang.ref,a
subpackageofjava.lang).
bootclasspathclasspathlist
Specifiesthepathswherethebootclassesreside.ThesearenominallytheJavaplatformclasses.ThebootclasspathispartofthesearchpaththeJavadoctoolwillusetolookup
sourceandclassfiles.SeeHowClassesAreFound.formoredetails.Separatedirectoriesinclasspathlistwithsemicolons().
extdirsdirlist
Specifiesthedirectorieswhereextensionclassesreside.TheseareanyclassesthatusetheJavaExtensionmechanism.TheextdirsispartofthesearchpaththeJavadoctoolwill
usetolookupsourceandclassfiles.Seeclasspath(above)formoredetails.Separatedirectoriesindirlistwithsemicolons().
verbose
Providesmoredetailedmessageswhilejavadocisrunning.Withouttheverboseoption,messagesappearforloadingthesourcefiles,generatingthedocumentation(onemessage
persourcefile),andsorting.Theverboseoptioncausestheprintingofadditionalmessagesspecifyingthenumberofmillisecondstoparseeachjavasourcefile.
quiet
Shutsoffnonerrorandnonwarningmessages,leavingonlythewarningsanderrorsappear,makingthemeasiertoview.Alsosuppressestheversionstring.
breakiterator
Usestheinternationalizedsentenceboundaryofjava.text.BreakIteratortodeterminetheendofthefirstsentenceforEnglish(allotherlocalesalreadyuseBreakIterator),
ratherthananEnglishlanguage,localespecificalgorithm.Byfirstsentence,wemeanthefirstsentenceinthemaindescriptionofapackage,classormember.Thissentenceis
copiedtothepackage,classormembersummary,andtothealphabeticindex.
FromJDK1.2forward,theBreakIteratorclassisalreadyusedtodeterminetheendofsentenceforalllanguagesbutEnglish.Therefore,thebreakiteratoroptionhasnoeffect
exceptforEnglishfrom1.2forward.Englishhasitsowndefaultalgorithm:
EnglishdefaultsentencebreakalgorithmStopsataperiodfollowedbyaspaceoraHTMLblocktag,suchas.
BreakiteratorsentencebreakalgorithmIngeneral,stopsataperiod,questionmarkorexclamationmarkfollowedbyaspaceifthenextwordstartswithacapitalletter.Thisis
meanttohandlemostabbreviations(suchas"Theserialno.isvalid",butwon'thandle"Mr.Smith").Doesn'tstopatHTMLtagsorsentencesthatbeginwithnumbersorsymbols.
Stopsatthelastperiodin"../filename",evenifembeddedinanHTMLtag.
NOTE:Weremovedthebreakiteratorwarningmessagesfrom1.5.0thatwerein1.4.xandleftthedefaultsentencebreakalgorithmunchanged.Thatis,thebreakiterator
optionisnotthedefaultin1.5.0,nordoweexpectittobecomethedefault.Thisisareversalfromourformerintentionthatthedefaultwouldchangeinthe"nextmajorrelease"
(1.5.0).Thismeansifyouhavenotmodifiedyoursourcecodetoeliminatethebreakiteratorwarningsin1.4.x,thenyoudon'thavetodoanything,andthewarningsgoaway
startingwith1.5.0.Thereasonforthisreversalisbecauseanybenefittohavingbreakiteratorbecomethedefaultwouldbeoutweighedbytheincompatiblesourcechangeit
wouldrequire.Weregretanyextraworkandconfusionthishascaused.
localelanguage_country_variant
ImportantThelocaleoptionmustbeplacedahead(totheleft)ofanyoptionsprovidedbythestandarddocletoranyotherdoclet.Otherwise,thenavigationbarswillappearin
English.Thisistheonlycommandlineoptionthatisorderdependent.
Specifiesthelocalethatjavadocuseswhengeneratingdocumentation.Theargumentisthenameofthelocale,asdescribedinjava.util.Localedocumentation,suchasen_US
(English,UnitedStates)oren_US_WIN(Windowsvariant).
Specifyingalocalecausesjavadoctochoosetheresourcefilesofthatlocaleformessages(stringsinthenavigationbar,headingsforlistsandtables,helpfilecontents,comments
instylesheet.css,andsoforth).Italsospecifiesthesortingorderforlistssortedalphabetically,andthesentenceseparatortodeterminetheendofthefirstsentence.Itdoesnot
determinethelocaleofthedoccommenttextspecifiedinthesourcefilesofthedocumentedclasses.
encodingname
Specifiestheencodingnameofthesourcefiles,suchasEUCJIS/SJIS.Ifthisoptionisnotspecified,theplatformdefaultconverterisused.
Alsoseedocencodingandcharset.
Jflag
Passesflagdirectlytotheruntimesystemjavathatrunsjavadoc.NoticetheremustbenospacebetweentheJandtheflag.Forexample,ifyouneedtoensurethatthesystemsets
aside32megabytesofmemoryinwhichtoprocessthegenerateddocumentation,thenyouwouldcalltheXmxoptionofjavaasfollows(Xmsisoptional,asitonlysetsthesizeof
initialmemory,whichisusefulifyouknowtheminimumamountofmemoryrequired):
C:>javadocJXmx32mJXms32mcom.mypackage
Totellwhatversionofjavadocyouareusing,callthe"version"optionofjava:
C:>javadocJversion
javaversion"1.2"
ClassicVM(buildJDK1.2V,greenthreads,sunwjit)
(Theversionnumberofthestandarddocletappearsinitsoutputstream.)
OptionsProvidedbytheStandardDoclet
ddirectory
SpecifiesthedestinationdirectorywherejavadocsavesthegeneratedHTMLfiles.(The"d"means"destination.")Omittingthisoptioncausesthefilestobesavedtothecurrent
directory.Thevaluedirectorycanbeabsolute,orrelativetothecurrentworkingdirectory.Asof1.4,thedestinationdirectoryisautomaticallycreatedwhenjavadocisrun.
Forexample,thefollowinggeneratesthedocumentationforthepackagecom.mypackageandsavestheresultsintheC:\user\doc\directory:
C:>javadocd\user\doccom.mypackage
use
Includesone"Use"pageforeachdocumentedclassandpackage.Thepagedescribeswhatpackages,classes,methods,constructorsandfieldsuseanyAPIofthegivenclassor
package.GivenclassC,thingsthatuseclassCwouldincludesubclassesofC,fieldsdeclaredasC,methodsthatreturnC,andmethodsandconstructorswithparametersoftype
C.
Forexample,let'slookatwhatmightappearonthe"Use"pageforString.ThegetName()methodinthejava.awt.FontclassreturnstypeString.Therefore,getName()uses
String,andyouwillfindthatmethodonthe"Use"pageforString.
NotethatthisdocumentsonlyusesoftheAPI,nottheimplementation.IfamethodusesStringinitsimplementationbutdoesnottakeastringasanargumentorreturnastring,that
isnotconsidereda"use"ofString.
Youcanaccessthegenerated"Use"pagebyfirstgoingtotheclassorpackage,thenclickingonthe"Use"linkinthenavigationbar.
version
Includesthe@versiontextinthegenerateddocs.Thistextisomittedbydefault.TotellwhatversionoftheJavadoctoolyouareusing,usetheJversionoption.
author
Includesthe@authortextinthegenerateddocs.
splitindex
Splitstheindexfileintomultiplefiles,alphabetically,onefileperletter,plusafileforanyindexentriesthatstartwithnonalphabeticalcharacters.
windowtitletitle
SpecifiesthetitletobeplacedintheHTML<title>tag.Thisappearsinthewindowtitleandinanybrowserbookmarks(favoriteplaces)thatsomeonecreatesforthispage.Thistitle
shouldnotcontainanyHTMLtags,asthebrowserwillnotproperlyinterpretthem.Anyinternalquotationmarkswithintitlemayhavetobeescaped.Ifwindowtitleisomitted,the
Javadoctoolusesthevalueofdoctitleforthisoption.
C:>javadocwindowtitle"JavaSEPlatform"com.mypackage
doctitletitle
Specifiesthetitletobeplacednearthetopoftheoverviewsummaryfile.Thetitlewillbeplacedasacentered,leveloneheadingdirectlybeneaththeuppernavigationbar.Thetitle
maycontainhtmltagsandwhitespace,thoughifitdoes,itmustbeenclosedinquotes.Anyinternalquotationmarkswithintitlemayhavetobeescaped.
C:>javadocdoctitle"Java"com.mypackage
titletitle
Thisoptionnolongerexists.ItexistedonlyinBetaversionsofJavadoc1.2.Ithasbeenrenamedtodoctitle.Thisoptionisbeingrenamedtomakeitclearthatitdefinesthe
documenttitleratherthanthewindowtitle.
headerheader
Specifiestheheadertexttobeplacedatthetopofeachoutputfile.Theheaderwillbeplacedtotherightoftheuppernavigationbar.headermaycontainHTMLtagsandwhitespace,
thoughifitdoes,itmustbeenclosedinquotes.Anyinternalquotationmarkswithinheadermayhavetobeescaped.
C:>javadocheader"Java2Platform v1.4"com.mypackage
footerfooter
Specifiesthefootertexttobeplacedatthebottomofeachoutputfile.Thefooterwillbeplacedtotherightofthelowernavigationbar.footermaycontainhtmltagsandwhitespace,
thoughifitdoes,itmustbeenclosedinquotes.Anyinternalquotationmarkswithinfootermayhavetobeescaped.
top
Specifiesthetexttobeplacedatthetopofeachoutputfile.
bottomtext
Specifiesthetexttobeplacedatthebottomofeachoutputfile.Thetextwillbeplacedatthebottomofthepage,belowthelowernavigationbar.ThetextmaycontainHTMLtagsand
whitespace,thoughifitdoes,itmustbeenclosedinquotes.Anyinternalquotationmarkswithintextmayhavetobeescaped.
linkextdocURL
Createslinkstoexistingjavadocgenerateddocumentationofexternalreferencedclasses.Ittakesoneargument:
extdocURListheabsoluteorrelativeURLofthedirectorycontainingtheexternaljavadocgenerateddocumentationyouwanttolinkto.Examplesareshownbelow.The
packagelistfilemustbefoundinthisdirectory(otherwise,uselinkoffline).TheJavadoctoolreadsthepackagenamesfromthepackagelistfileandthenlinkstothose
packagesatthatURL.WhentheJavadoctoolisrun,theextdocURLvalueiscopiedliterallyintothe<AHREF>linksthatarecreated.Therefore,extdocURLmustbetheURLto
thedirectory,nottoafile.
YoucanuseanabsolutelinkforextdocURLtoenableyourdocstolinktoadocumentonanywebsite,orcanusearelativelinktolinkonlytoarelativelocation.Ifrelative,the
valueyoupassinshouldbetherelativepathfromthedestinationdirectory(specifiedwithd)tothedirectorycontainingthepackagesbeinglinkedto.
Whenspecifyinganabsolutelinkyounormallyuseanhttp:link.However,ifyouwanttolinktoafilesystemthathasnowebserver,youcanuseafile:linkhowever,dothis
onlyifeveryonewantingtoaccessthegenerateddocumentationsharesthesamefilesystem.
Inallcases,andonalloperatingsystems,youshoulduseaforwardslashastheseparator,whethertheURLisabsoluteorrelative,and"http:"or"file:"based(asspecifiedin
theURLMemo).
Absolutehttp:basedlink:
linkhttp://<host>/<directory>/<directory>/.../<name>
Absolutefile:basedlink:
linkfile://<host>/<directory>/<directory>/.../<name>
Relativelink:
link<directory>/<directory>/.../<name>
Youcanspecifymultiplelinkoptionsinagivenjavadocruntolinktomultipledocuments.
Choosingbetweenlinkofflineandlink:
Uselink:
whenusingarelativepathtotheexternalAPIdocument,or
whenusinganabsoluteURLtotheexternalAPIdocument,ifyourshellallowsaprogramtoopenaconnectiontothatURLforreading.
Uselinkoffline:
whenusinganabsoluteURLtotheexternalAPIdocument,ifyourshelldoesnotallowaprogramtoopenaconnectiontothatURLforreading.Thiscanoccurifyouarebehinda
firewallandthedocumentyouwanttolinktoisontheotherside.
ExampleusingabsolutelinkstotheexternaldocsLetussayyouwanttolinktothejava.lang,java.ioandotherJavaSEPlatformpackagesat
http://docs.oracle.com/javase/7/docs/api/,Thefollowingcommandgeneratesdocumentationforthepackagecom.mypackagewithlinkstotheJavaSEPlatform
packages.ThegenerateddocumentationwillcontainlinkstotheObjectclass,forexample,intheclasstrees.(Otheroptions,suchassourcepathandd,arenotshown.)
C:>javadoclinkhttp://docs.oracle.com/javase/7/docs/api/com.mypackage
ExampleusingrelativelinkstotheexternaldocsLet'ssayyouhavetwopackageswhosedocsaregeneratedindifferentrunsoftheJavadoctool,andthosedocsareseparatedby
arelativepath.Inthisexample,thepackagesarecom.apipackage,anAPI,andcom.spipackage,anSPI(ServiceProvideInterface).Youwantthedocumentationtoresidein
docs/api/com/apipackageanddocs/spi/com/spipackage.AssumingtheAPIpackagedocumentationisalreadygenerated,andthatdocsisthecurrentdirectory,youwould
documenttheSPIpackagewithlinkstotheAPIdocumentationbyrunning:
C:>javadocd./spilink../apicom.spipackage
Noticethelinkargumentisrelativetothedestinationdirectory(docs/spi).
DetailsThelinkoptionenablesyoutolinktoclassesreferencedtobyyourcodebutnotdocumentedinthecurrentjavadocrun.Fortheselinkstogotovalidpages,youmust
knowwherethoseHTMLpagesarelocated,andspecifythatlocationwithextdocURL.Thisallows,forinstance,thirdpartydocumentationtolinktojava.*documentationon
http://docs.oracle.com.
OmitthelinkoptionforjavadoctocreatelinksonlytoAPIwithinthedocumentationitisgeneratinginthecurrentrun.(Withoutthelinkoption,theJavadoctooldoesnotcreate
linkstodocumentationforexternalreferences,becauseitdoesnotknowiforwherethatdocumentationexists.)
Thisoptioncancreatelinksinseveralplacesinthegenerateddocumentation.
Anotheruseisforcrosslinksbetweensetsofpackages:Executejavadocononesetofpackages,thenrunjavadocagainonanothersetofpackages,creatinglinksbothways
betweenbothsets.
HowaClassMustbeReferencedForalinktoanexternalreferencedclasstoactuallyappear(andnotjustitstextlabel),theclassmustbereferencedinthefollowingway.Itisnot
sufficientforittobereferencedinthebodyofamethod.Itmustbereferencedineitheranimportstatementorinadeclaration.Hereareexamplesofhowtheclassjava.io.File
canbereferenced:
Inanykindofimportstatement:bywildcardimport,importexplicitlybyname,orautomaticallyimportforjava.lang.*.Forexample,thiswouldsuffice:
importjava.io.*
In1.3.xand1.2.x,onlyanexplicitimportbynameworksawildcardimportstatementdoesnotwork,nordoestheautomaticimportjava.lang.*.
Inadeclaration:
voidfoo(Filef){}
Thereferenceandbeinthereturntypeorparametertypeofamethod,constructor,field,classorinterface,orinanimplements,extendsorthrowsstatement.
Animportantcorollaryisthatwhenyouusethelinkoption,theremaybemanylinksthatunintentionallydonotappearduetothisconstraint.(Thetextwouldappearwithouta
hypertextlink.)Youcandetectthesebythewarningstheyemit.Themostinnocuouswaytoproperlyreferenceaclassandtherebyaddthelinkwouldbetoimportthatclass,asshown
above.
PackageListThelinkoptionrequiresthatafilenamedpackagelist,whichisgeneratedbytheJavadoctool,existattheURLyouspecifywithlink.Thepackagelistfileis
asimpletextfilethatliststhenamesofpackagesdocumentedatthatlocation.Intheearlierexample,theJavadoctoollooksforafilenamedpackagelistatthegivenURL,reads
inthepackagenamesandthenlinkstothosepackagesatthatURL.
Forexample,thepackagelistfortheJavaSEAPIislocatedathttp://docs.oracle.com/javase/7/docs/api/packagelistandstartsasfollows:
java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
etc.
Whenjavadocisrunwithoutthelinkoption,whenitencountersanamethatbelongstoanexternalreferencedclass,itprintsthenamewithnolink.However,whenthelink
optionisused,theJavadoctoolsearchesthepackagelistfileatthespecifiedextdocURLlocationforthatpackagename.Ifitfindsthepackagename,itprefixesthenamewith
extdocURL.
Inorderfortheretobenobrokenlinks,allofthedocumentationfortheexternalreferencesmustexistatthespecifiedURLs.TheJavadoctoolwillnotcheckthatthesepagesexist
onlythatthepackagelistexists.
MultipleLinksYoucansupplymultiplelinkoptionstolinktoanynumberofexternalgenerateddocuments.Javadoc1.2hasaknownbugwhichpreventsyoufromsupplying
morethanonelinkcommand.Thiswasfixedin1.2.2.
Specifyadifferentlinkoptionforeachexternaldocumenttolinkto:
C:>javadoclinkextdocURL1linkextdocURL2...linkextdocURLncom.mypackage
whereextdocURL1,extdocURL2,...extdocURLnpointrespectivelytotherootsofexternaldocuments,eachofwhichcontainsafilenamedpackagelist.
CrosslinksNotethat"bootstrapping"mayberequiredwhencrosslinkingtwoormoredocumentsthathavenotpreviouslybeengenerated.Inotherwords,ifpackagelistdoes
notexistforeitherdocument,whenyouruntheJavadoctoolonthefirstdocument,thepackagelistwillnotyetexistfortheseconddocument.Therefore,tocreatetheexternallinks,
youmustregeneratethefirstdocumentaftergeneratingtheseconddocument.
Inthiscase,thepurposeoffirstgeneratingadocumentistocreateitspackagelist(oryoucancreateitbyhanditifyou'recertainofthepackagenames).Thengeneratethe
seconddocumentwithitsexternallinks.TheJavadoctoolprintsawarningifaneededexternalpackagelistfiledoesnotexist.
linkofflineextdocURLpackagelistLoc
Thisoptionisavariationoflinktheybothcreatelinkstojavadocgenerateddocumentationforexternalreferencedclasses.Usethelinkofflineoptionwhenlinkingtoa
documentonthewebwhentheJavadoctoolitselfis"offline"thatis,itcannotaccessthedocumentthroughawebconnection.
Morespecifically,uselinkofflineiftheexternaldocument'spackagelistfileisnotaccessibleordoesnotexistattheextdocURLlocationbutdoesexistatadifferentlocation,
whichcanbespecifiedbypackageListLoc(typicallylocal).Thus,ifextdocURLisaccessibleonlyontheWorldWideWeb,linkofflineremovestheconstraintthattheJavadoctool
haveawebconnectionwhengeneratingthedocumentation.
Anotheruseisasa"hack"toupdatedocs:Afteryouhaverunjavadoconafullsetofpackages,thenyoucanrunjavadocagainononlyasmallersetofchangedpackages,sothatthe
updatedfilescanbeinsertedbackintotheoriginalset.Examplesaregivenbelow.
Thelinkofflineoptiontakestwoargumentsthefirstforthestringtobeembeddedinthe<ahref>links,thesecondtellingitwheretofindpackagelist:
extdocURListheabsoluteorrelativeURLofthedirectorycontainingtheexternaljavadocgenerateddocumentationyouwanttolinkto.Ifrelative,thevalueshouldbetherelative
pathfromthedestinationdirectory(specifiedwithd)totherootofthepackagesbeinglinkedto.Formoredetails,seeextdocURLinthelinkoption.
packagelistLocisthepathorURLtothedirectorycontainingthepackagelistfilefortheexternaldocumentation.ThiscanbeaURL(http:orfile:)orfilepath,andcanbe
absoluteorrelative.Ifrelative,makeitrelativetothecurrentdirectoryfromwherejavadocwasrun.Donotincludethepackagelistfilename.
Youcanspecifymultiplelinkofflineoptionsinagivenjavadocrun.(Priorto1.2.2,itcouldbespecifiedonlyonce.)
ExampleusingabsolutelinkstotheexternaldocsLetussayyouwanttolinktothejava.lang,java.ioandotherJavaSEPlatformpackagesat
http://docs.oracle.com/javase/7/docs/api/,butyourshelldoesnothavewebaccess.Youcouldopenthepackagelistfileinabrowserat
http://docs.oracle.com/javase/7/docs/api/packagelist,saveittoalocaldirectory,andpointtothislocalcopywiththesecondargument,packagelistLoc.Inthisexample,
thepackagelistfilehasbeensavedtothecurrentdirectory".".Thefollowingcommandgeneratesdocumentationforthepackagecom.mypackagewithlinkstotheJavaSEPlatform
packages.ThegenerateddocumentationwillcontainlinkstotheObjectclass,forexample,intheclasstrees.(Othernecessaryoptions,suchassourcepath,arenotshown.)
C:>javadoclinkofflinehttp://docs.oracle.com/javase/7/docs/api/.com.mypackage
ExampleusingrelativelinkstotheexternaldocsIt'snotverycommontouselinkofflinewithrelativepaths,forthesimplereasonthatlinkusuallysuffices.Whenusing
linkoffline,thepackagelistfileisgenerallylocal,andwhenusingrelativelinks,thefileyouarelinkingtoisalsogenerallylocal.Soitisusuallyunnecessarytogiveadifferent
pathforthetwoargumentstolinkoffline.Whenthetwoargumentsareidentical,youcanuselink.Seethelinkrelativeexample.
ManuallyCreatingapackagelistFileIfapackagelistfiledoesnotyetexist,butyouknowwhatpackagenamesyourdocumentwilllinkto,youcancreateyourowncopyofthis
filebyhandandspecifyitspathwithpackagelistLoc.Anexamplewouldbethepreviouscasewherethepackagelistforcom.spipackagedidnotexistwhencom.apipackagewas
firstgenerated.Thistechniqueisusefulwhenyouneedtogeneratedocumentationthatlinkstonewexternaldocumentationwhosepackagenamesyouknow,butwhichisnotyet
published.ThisisalsoawayofcreatingpackagelistfilesforpackagesgeneratedwithJavadoc1.0or1.1,wherepackagelistfileswerenotgenerated.Likewise,two
companiescansharetheirunpublishedpackagelistfiles,enablingthemtoreleasetheircrosslinkeddocumentationsimultaneously.
LinkingtoMultipleDocumentsYoucanincludelinkofflineonceforeachgenerateddocumentyouwanttoreferto(eachoptionisshownonaseparatelineforclarity):
C:>javadoclinkofflineextdocURL1packagelistLoc1\
linkofflineextdocURL2packagelistLoc2\
...
UpdatingdocsAnotheruseforlinkofflineoptionisusefulifyourprojecthasdozensorhundredsofpackages,ifyouhavealreadyrunjavadocontheentiretree,andnow,ina
separaterun,youwanttoquicklymakesomesmallchangesandrerunjavadoconjustasmallportionofthesourcetree.Thisissomewhatofahackinthatitworksproperlyonlyif
yourchangesareonlytodoccommentsandnottodeclarations.Ifyouweretoadd,removeorchangeanydeclarationsfromthesourcecode,thenbrokenlinkscouldshowupinthe
index,packagetree,inheritedmemberlists,usepage,andotherplaces.
First,youcreateanewdestinationdirectory(callitupdate)forthisnewsmallrun.Let'ssaytheoriginaldestinationdirectorywasnamedhtml.Inthesimplestexample,cdtothe
parentofhtml.Setthefirstargumentoflinkofflinetothecurrentdirectory"."andsetthesecondargumenttotherelativepathtohtml,whereitcanfindpackagelist,andpass
inonlythepackagenamesofthepackagesyouwanttoupdate:
C:>javadocdupdatelinkoffline.htmlcom.mypackage
WhentheJavadoctoolisdone,copythesegeneratedclasspagesinupdate\com\package(nottheovervieworindex),overtheoriginalfilesinhtml\com\package.
linksource
CreatesanHTMLversionofeachsourcefile(withlinenumbers)andaddslinkstothemfromthestandardHTMLdocumentation.Linksarecreatedforclasses,interfaces,
constructors,methodsandfieldswhosedeclarationsareinasourcefile.Otherwise,linksarenotcreated,suchasfordefaultconstructorsandgeneratedclasses.
Thisoptionexposesallprivateimplementationdetailsintheincludedsourcefiles,includingprivateclasses,privatefields,andthebodiesofprivatemethods,regardlessofthe
public,package,protectedandprivateoptions.Unlessyoualsousetheprivateoption,notallprivateclassesorinterfaceswillnecessarilybeaccessiblevialinks.
Eachlinkappearsonthenameoftheidentifierinitsdeclaration.Forexample,thelinktothesourcecodeoftheButtonclasswouldbeontheword"Button":
publicclassButton
extendsComponent
implementsAccessible
andthelinktothesourcecodeofthegetLabel()methodintheButtonclasswouldbeontheword"getLabel":
publicStringgetLabel()
groupgroupheadingpackagepattern:packagepattern:...
Separatespackagesontheoverviewpageintowhatevergroupsyouspecify,onegrouppertable.Youspecifyeachgroupwithadifferentgroupoption.Thegroupsappearonthe
pageintheorderspecifiedonthecommandlinepackagesarealphabetizedwithinagroup.Foragivengroupoption,thepackagesmatchingthelistofpackagepattern
expressionsappearinatablewiththeheadinggroupheading.
groupheadingcanbeanytext,andcanincludewhitespace.Thistextisplacedinthetableheadingforthegroup.
packagepatterncanbeanypackagename,orcanbethestartofanypackagenamefollowedbyanasterisk(*).Theasteriskisawildcardmeaning"matchanycharacters".This
istheonlywildcardallowed.Multiplepatternscanbeincludedinagroupbyseparatingthemwithcolons(:).
NOTE:Ifusinganasteriskinapatternorpatternlist,thepatternlistmustbeinsidequotes,suchas"java.lang*:java.util"
Ifyoudonotsupplyanygroupoption,allpackagesareplacedinonegroupwiththeheading"Packages".Iftheallgroupsdonotincludealldocumentedpackages,anyleftover
packagesappearinaseparategroupwiththeheading"OtherPackages".
Forexample,thefollowingoptionseparatesthefourdocumentedpackagesintocore,extensionandotherpackages.Noticethetrailing"dot"doesnotappearin"java.lang*"
includingthedot,suchas"java.lang.*"wouldomitthejava.langpackage.
C:>javadocgroup"CorePackages""java.lang*:java.util"
group"ExtensionPackages""javax.*"
java.langjava.lang.reflectjava.utiljavax.servletjava.new
Thisresultsinthegroupings:
CorePackages
java.lang
java.lang.reflect
java.util
ExtensionPackages
javax.servlet
OtherPackages
java.new
nodeprecated
PreventsthegenerationofanydeprecatedAPIatallinthedocumentation.Thisdoeswhatnodeprecatedlistdoes,plusitdoesnotgenerateanydeprecatedAPIthroughouttherestof
thedocumentation.Thisisusefulwhenwritingcodeandyoudon'twanttobedistractedbythedeprecatedcode.
nodeprecatedlist
PreventsthegenerationofthefilecontainingthelistofdeprecatedAPIs(deprecatedlist.html)andthelinkinthenavigationbartothatpage.(However,javadoccontinuestogenerate
thedeprecatedAPIthroughouttherestofthedocument.)ThisisusefulifyoursourcecodecontainsnodeprecatedAPI,andyouwanttomakethenavigationbarcleaner.
nosince
Omitsfromthegenerateddocsthe"Since"sectionsassociatedwiththe@sincetags.
notree
Omitstheclass/interfacehierarchypagesfromthegenerateddocs.Thesearethepagesyoureachusingthe"Tree"buttoninthenavigationbar.Thehierarchyisproducedbydefault.
noindex
Omitstheindexfromthegenerateddocs.Theindexisproducedbydefault.
nohelp
OmitstheHELPlinkinthenavigationbarsatthetopandbottomofeachpageofoutput.
nonavbar
Preventsthegenerationofthenavigationbar,headerandfooter,otherwisefoundatthetopandbottomofthegeneratedpages.Hasnoaffectonthe"bottom"option.Thenonavbar
optionisusefulwhenyouareinterestedonlyinthecontentandhavenoneedfornavigation,suchasconvertingthefilestoPostScriptorPDFforprintonly.
helpfilepath\filename
Specifiesthepathofanalternatehelpfilepath\filenamethattheHELPlinkinthetopandbottomnavigationbarslinkto.Withoutthisoption,theJavadoctoolautomaticallycreatesa
helpfilehelpdoc.htmlthatishardcodedintheJavadoctool.Thisoptionenablesyoutooverridethisdefault.Thefilenamecanbeanynameandisnotrestrictedtohelp
doc.htmltheJavadoctoolwilladjustthelinksinthenavigationbaraccordingly.Forexample:
C:>javadochelpfileC:\user\myhelp.htmljava.awt
stylesheetfilepath\filename
SpecifiesthepathofanalternateHTMLstylesheetfile.Withoutthisoption,theJavadoctoolautomaticallycreatesastylesheetfilestylesheet.cssthatishardcodedintheJavadoc
tool.Thisoptionenablesyoutooverridethisdefault.Thefilenamecanbeanynameandisnotrestrictedtostylesheet.css.Forexample:
C:>javadocstylesheetfileC:\user\mystylesheet.csscom.mypackage
serialwarn
Generatescompiletimewarningsformissing@serialtags.Bydefault,Javadoc1.2.2(andlaterversions)generatesnoserialwarnings.(Thisisareversalfromearlierversions.)
Usethisoptiontodisplaytheserialwarnings,whichhelpstoproperlydocumentdefaultserializablefieldsandwriteExternalmethods.
charsetname
SpecifiestheHTMLcharactersetforthisdocument.ThenameshouldbeapreferredMIMEnameasgivenintheIANARegistry.Forexample:
C:>javadoccharset"iso88591"mypackage
wouldinsertthefollowinglineintheheadofeverygeneratedpage:
<METAhttpequiv="ContentType"content="text/htmlcharset=ISO88591">
ThisMETAtagisdescribedintheHTMLstandard.(4197265and4137321)
Alsoseeencodinganddocencoding.
docencodingname
SpecifiestheencodingofthegeneratedHTMLfiles.ThenameshouldbeapreferredMIMEnameasgivenintheIANARegistry.Ifyouomitthisoptionbutuseencoding,thenthe
encodingofthegeneratedHTMLfilesisdeterminedbyencoding.Example:
%javadocdocencoding"ISO88591"mypackage
Alsoseeencodingandcharset.
keywords
AddsHTMLmetakeywordtagstothegeneratedfileforeachclass.Thesetagscanhelpthepagebefoundbysearchenginesthatlookformetatags.(Mostsearchenginesthat
searchtheentireInternetdonotlookatmetatags,becausepagescanmisusethembutsearchenginesofferedbycompaniesthatconfinetheirsearchtotheirownwebsitecan
benefitbylookingatmetatags.)
Themetatagsincludethefullyqualifiednameoftheclassandtheunqualifiednamesofthefieldsandmethods.Constructorsarenotincludedbecausetheyareidenticaltotheclass
name.Forexample,theclassStringstartswiththesekeywords:
<METANAME="keywords"CONTENT="java.lang.Stringclass">
<METANAME="keywords"CONTENT="CASE_INSENSITIVE_ORDER">
<METANAME="keywords"CONTENT="length()">
<METANAME="keywords"CONTENT="charAt()">
tagtagname:Xaoptcmf:"taghead"
EnablestheJavadoctooltointerpretasimple,oneargumentcustomblocktag@tagnameindoccomments.SotheJavadoctoolcan"spellcheck"tagnames,itisimportantto
includeatagoptionforeverycustomtagthatispresentinthesourcecode,disabling(withX)thosethatarenotbeingoutputinthecurrentrun.
Thecolon(:)isalwaystheseparator.Touseacolonintagname,seeUseofColoninTagName.
Thetagoptionoutputsthetag'sheadingtagheadinbold,followedonthenextlinebythetextfromitssingleargument,asshownintheexamplebelow.Likeanyblocktag,this
argument'stextcancontaininlinetags,whicharealsointerpreted.Theoutputissimilartostandardoneargumenttags,suchas@returnand@author.Omittingtagheadcauses
tagnametoappearastheheading.
PlacementoftagsTheXaoptcmfpartoftheargumentdetermineswhereinthesourcecodethetagisallowedtobeplaced,andwhetherthetagcanbedisabled(usingX).Youcan
supplyeithera,toallowthetaginallplaces,oranycombinationoftheotherletters:
X(disabletag)
a(all)
o(overview)
p(packages)
t(types,thatisclassesandinterfaces)
c(constructors)
m(methods)
f(fields)
ExamplesofsingletagsAnexampleofatagoptionforatagthatcanbeusedanywhereinthesourcecodeis:
tagtodo:a:"ToDo:"
Ifyouwanted@todotobeusedonlywithconstructors,methodsandfields,youwoulduse:
tagtodo:cmf:"ToDo:"
Noticethelastcolon(:)aboveisnotaparameterseparator,butispartoftheheadingtext(asshownbelow).Youwoulduseeithertagoptionforsourcecodethatcontainsthetag
@todo,suchas:
@todoThedocumentationforthismethodneedswork.
Thislinewouldproduceoutputsomethinglike:
ToDo:
Thedocumentationforthismethodneedswork.
UseofColoninTagNameAcoloncanbeusedinatagnameifitisescapedwithabackslash.Forthisdoccomment:
/**
*@ejb:bean
*/
usethistagoption:
tagejb\:bean:a:"EJBBean:"
Spellcheckingtagnames(Disablingtags)Somedevelopersputcustomtagsinthesourcecodethattheydon'talwayswanttooutput.Inthesecases,itisimportanttolistalltags
thatarepresentinthesourcecode,enablingtheonesyouwanttooutputanddisablingtheonesyoudon'twanttooutput.ThepresenceofXdisablesthetag,whileitsabsence
enablesthetag.ThisgivestheJavadoctoolenoughinformationtoknowifatagitencountersisunknown,probablytheresultsofatypooramisspelling.Itprintsawarninginthese
cases.
YoucanaddXtotheplacementvaluesalreadypresent,sothatwhenyouwanttoenablethetag,youcansimplydeletetheX.Forexample,if@todoisatagthatyouwanttosuppress
onoutput,youwoulduse:
tagtodo:Xcmf:"ToDo:"
or,ifyou'dratherkeepitsimple:
tagtodo:X
Thesyntaxtagtodo:Xworksevenif@todoisdefinedbyataglet.
OrderoftagsTheorderofthetag(andtaglet)optionsdeterminetheorderthetagsareoutput.Youcanmixthecustomtagswiththestandardtagstointerspersethem.Thetag
optionsforstandardtagsareplaceholdersonlyfordeterminingtheordertheytakeonlythestandardtag'sname.(Subheadingsforstandardtagscannotbealtered.)Thisis
illustratedinthefollowingexample.
Iftagismissing,thenthepositionoftagletdeterminesitsorder.Iftheyarebothpresent,thenwhicheverappearslastonthecommandlinedeterminesitsorder.(Thishappens
becausethetagsandtagletsareprocessedintheorderthattheyappearonthecommandline.Forexample,iftagletandtagbothhavethename"todo",theonethatappears
lastonthecommandlinewilldetermineitsorder.
ExampleofacompletesetoftagsThisexampleinserts"ToDo"after"Parameters"andbefore"Throws"intheoutput.Byusing"X",italsospecifiesthat@exampleisatagthat
mightbeencounteredinthesourcecodethatshouldnotbeoutputduringthisrun.Noticethatifyouuse@argfile,youcanputthetagsonseparatelinesinanargumentfilelikethis
(nolinecontinuationcharactersneeded):
tagparam
tagreturn
tagtodo:a:"ToDo:"
tagthrows
tagsee
tagexample:X
Whenjavadocparsesthedoccomments,anytagencounteredthatisneitherastandardtagnorpassedinwithtagortagletisconsideredunknown,andawarningisthrown.
Thestandardtagsareinitiallystoredinternallyinalistintheirdefaultorder.Whenevertagoptionsareused,thosetagsgetappendedtothisliststandardtagsaremovedfrom
theirdefaultposition.Therefore,ifatagoptionisomittedforastandardtag,itremainsinitsdefaultposition.
AvoidingConflictsIfyouwanttosliceoutyourownnamespace,youcanuseadotseparatednamingconventionsimilartothatusedforpackages:com.mycompany.todo.Sunwill
continuetocreatestandardtagswhosenamesdonotcontaindots.AnytagyoucreatewilloverridethebehaviorofatagbythesamenamedefinedbySun.Inotherwords,ifyou
createatagortaglet@todo,itwillalwayshavethesamebehavioryoudefine,evenifSunlatercreatesastandardtagofthesamename.
Annotationsvs.JavadocTagsIngeneral,ifthemarkupyouwanttoaddisintendedtoaffectorproducedocumentation,itshouldprobablybeajavadoctagotherwise,itshouldbe
anannotation.SeeComparingAnnotationsandJavadocTags
Youcanalsocreatemorecomplexblocktags,orcustominlinetagswiththetagletoption.
tagletclass
Specifiestheclassfilethatstartsthetagletusedingeneratingthedocumentationforthattag.Usethefullyqualifiednameforclass.Thistagletalsodefinesthenumberoftext
argumentsthatthecustomtaghas.Thetagletacceptsthosearguments,processesthem,andgeneratestheoutput.Forextensivedocumentationwithexampletaglets,see:
TagletOverview
Tagletsareusefulforblockorinlinetags.Theycanhaveanynumberofargumentsandimplementcustombehavior,suchasmakingtextbold,formattingbullets,writingoutthetextto
afile,orstartingotherprocesses.
Tagletscanonlydeterminewhereatagshouldappearandinwhatform.Allotherdecisionsaremadebythedoclet.Soatagletcannotdothingssuchasremoveaclassnamefrom
thelistofincludedclasses.However,itcanexecutesideeffects,suchasprintingthetag'stexttoafileortriggeringanotherprocess.
Usethetagletpathoptiontospecifythepathtothetaglet.Hereisanexamplethatinsertsthe"ToDo"tagletafter"Parameters"andaheadof"Throws"inthegeneratedpages:
tagletcom.sun.tools.doclets.ToDoTaglet
tagletpath/home/taglets
tagreturn
tagparam
tagtodo
tagthrows
tagsee
Alternatively,youcanusethetagletoptioninplaceofitstagoption,butthatmaybehardertoread.
tagletpathtagletpathlist
Specifiesthesearchpathsforfindingtagletclassfiles(.class).Thetagletpathlistcancontainmultiplepathsbyseparatingthemwithacolon(:).TheJavadoctoolwillsearchinall
subdirectoriesofthespecifiedpaths.
docfilessubdirs
Enablesdeepcopyingof"docfiles"directories.Inotherwords,subdirectoriesandallcontentsarerecursivelycopiedtothedestination.Forexample,thedirectorydoc
files/example/imagesandallitscontentswouldnowbecopied.Thereisalsoanoptiontoexcludesubdirectories.
excludedocfilessubdirname1:name2...
Excludesany"docfiles"subdirectorieswiththegivennames.ThispreventsthecopyingofSCCSandothersourcecodecontrolsubdirectories.
noqualifierall|packagename1:packagename2:...
Omitsqualifyingpackagenamefromaheadofclassnamesinoutput.Theargumenttonoqualifieriseither"all"(allpackagequalifiersareomitted)oracolonseparatelistof
packages,withwildcards,toberemovedasqualifiers.Thepackagenameisremovedfromplaceswhereclassorinterfacenamesappear.
Thefollowingexampleomitsallpackagequalifiers:
noqualifierall
Thefollowingexampleomits"java.lang"and"java.io"packagequalifiers:
noqualifierjava.lang:java.io
Thefollowingexampleomitspackagequalifiersstartingwith"java",and"com.sun"subpackages(butnot"javax"):
noqualifierjava.*:com.sun.*
Whereapackagequalifierwouldappearduetotheabovebehavior,thenamecanbesuitablyshortenedseeHowanameisdisplayed.Thisruleisineffectwhetherornot
noqualifierisused.
notimestamp
Suppressesthetimestamp,whichishiddeninanHTMLcommentinthegeneratedHTMLnearthetopofeachpage.Usefulwhenyouwanttorunjavadocontwosourcebasesand
diffthem,asitpreventstimestampsfromcausingadiff(whichwouldotherwisebeadiffoneverypage).Thetimestampincludesthejavadocversionnumber,andcurrentlylookslike
this:
<!Generatedbyjavadoc(build1.5.0_01)onThuApr0214:04:52IST2009>
nocomment
Suppresstheentirecommentbody,includingthemaindescriptionandalltags,generatingonlydeclarations.Thisoptionenablesreusingsourcefilesoriginallyintendedfora
differentpurpose,toproduceskeletonHTMLdocumentationattheearlystagesofanewproject.
sourcetabtabLength
Specifythenumberofspaceseachtabtakesupinthesource.
COMMANDLINEARGUMENTFILES
Toshortenorsimplifythejavadoccommandline,youcanspecifyoneormorefilesthatthemselvescontainargumentstothejavadoccommand(exceptJoptions).Thisenablesyouto
createjavadoccommandsofanylengthonanyoperatingsystem.
Anargumentfilecanincludejavadocoptionsandsourcefilenamesinanycombination.Theargumentswithinafilecanbespaceseparatedornewlineseparated.Ifafilenamecontains
embeddedspaces,putthewholefilenameindoublequotes,anddoubleeachbackslash("MyFiles\\Stuff.java").
Filenameswithinanargumentfilearerelativetothecurrentdirectory,notthelocationoftheargumentfile.Wildcards(*)arenotallowedintheselists(suchasforspecifying*.java).Useof
the'@'charactertorecursivelyinterpretfilesisnotsupported.TheJoptionsarenotsupportedbecausetheyarepassedtothelauncher,whichdoesnotsupportargumentfiles.
Whenexecutingjavadoc,passinthepathandnameofeachargumentfilewiththe'@'leadingcharacter.Whenjavadocencountersanargumentbeginningwiththecharacter`@',itexpands
thecontentsofthatfileintotheargumentlist.
ExampleSingleArgFile
Youcoulduseasingleargumentfilenamed"argfile"toholdallJavadocarguments:
C:>javadoc@argfile
Thisargumentfilecouldcontainthecontentsofbothfilesshowninthenextexample.
ExampleTwoArgFiles
YoucancreatetwoargumentfilesonefortheJavadocoptionsandtheotherforthepackagenamesorsourcefilenames:(Noticethefollowinglistshavenolinecontinuationcharacters.)
Createafilenamed"options"containing:
ddocsfilelist
use
splitindex
windowtitle'JavaSE7APISpecification'
doctitle'JavaSE7APISpecification'
header'JavaSE7'
bottom'Copyright&copy19932011Oracleand/oritsaffiliates.Allrightsreserved.'
group"CorePackages""java.*"
overview\java\pubs\ws\1.7.0\src\share\classes\overviewcore.html
sourcepath\java\pubs\ws\1.7.0\src\share\classes
Createafilenamed"packages"containing:
com.mypackage1
com.mypackage2
com.mypackage3
Youwouldthenrunjavadocwith:
C:>javadoc@options@packages
ExampleArgFileswithPaths
Theargumentfilescanhavepaths,butanyfilenamesinsidethefilesarerelativetothecurrentworkingdirectory(notpath1orpath2):
C:>javadoc@path1\options@path2\packages
ExampleOptionArguments
Here'sanexampleofsavingjustanargumenttoajavadocoptioninanargumentfile.We'llusethebottomoption,sinceitcanhavealengthyargument.Youcouldcreateafilenamed
"bottom"containingitstextargument:
'<fontsize="1">
<ahref="http://bugreport.sun.com/bugreport/">Submitabugorfeature</a> 
Copyright&copy1993,2011,Oracleand/oritsaffiliates.Allrightsreserved. 
OracleisaregisteredtrademarkofOracleCorporationand/oritsaffiliates.
Othernamesmaybetrademarksoftheirrespectiveowners.'
ThenruntheJavadoctoolwith:
C:>javadocbottom@bottom@packages
Oryoucouldincludethebottomoptionatthestartoftheargumentfile,andthenjustrunitas:
C:>javadoc@bottom@packages
Running
RUNNINGJAVADOC
VersionNumbersTheversionnumberofjavadoccanbedeterminedusingjavadocJversion.Theversionnumberofthestandarddocletappearsinitsoutputstream.Itcanbeturnedoff
withquiet.
PublicprogrammaticinterfaceToinvoketheJavadoctoolfromwithinprogramswrittenintheJavalanguage.Thisinterfaceisincom.sun.tools.javadoc.Main(andjavadocisre
entrant).Formoredetails,seeStandardDoclet.
RunningDocletsTheinstructionsgivenbelowareforinvokingthestandardHTMLdoclet.Toinvokeacustomdoclet,usethedocletanddocletpathoptions.SeeDocletOverviewformore
information.
SIMPLEEXAMPLES
Youcanrunjavadoconentirepackagesorindividualsourcefiles.Eachpackagenamehasacorrespondingdirectoryname.Inthefollowingexamples,thesourcefilesarelocatedat
C:\home\src\java\awt\*java.ThedestinationdirectoryisC:\home\html.
DocumentingOneorMorePackages
Todocumentapackage,thesourcefiles(*.java)forthatpackagemustbelocatedinadirectoryhavingthesamenameasthepackage.Ifapackagenameismadeupofseveralidentifiers
(separatedbydots,suchasjava.awt.color),eachsubsequentidentifiermustcorrespondtoadeepersubdirectory(suchasjava/awt/color).Youmaysplitthesourcefilesforasingle
packageamongtwosuchdirectorytreeslocatedatdifferentplaces,aslongassourcepathpointstothembothforexamplesrc1\java\awt\colorandsrc2\java\awt\color.
Youcanrunjavadoceitherbychangingdirectories(withcd)orbyusingsourcepathoption.Theexamplesbelowillustratebothalternatives.
Case1RunrecursivelystartingfromoneormorepackagesThisexampleusessourcepathsojavadoccanberunfromanydirectoryandsubpackages(anew1.4option)for
recursion.Ittraversesthesubpackagesofthejavadirectoryexcludingpackagesrootedatjava.netandjava.lang.Noticethisexcludesjava.lang.ref,asubpackageof
java.lang).
%javadocd\home\htmlsourcepath\home\srcsubpackagesjavaexcludejava.net:java.lang
Toalsotraversedownotherpackagetrees,appendtheirnamestothesubpackagesargument,suchasjava:javax:org.xml.sax.
Case2Runonexplicitpackagesafterchangingtothe"root"sourcedirectoryChangetotheparentdirectoryofthefullyqualifiedpackage.Thenrunjavadoc,supplyingnamesof
oneormorepackagesyouwanttodocument:
C:>cdC:\home\src\
C:>javadocdC:\home\htmljava.awtjava.awt.event
Case3RunfromanydirectoryonexplicitpackagesinasingledirectorytreeInthiscase,itdoesn'tmatterwhatthecurrentdirectoryis.Runjavadocsupplyingsourcepathwith
theparentdirectoryofthetoplevelpackage,andsupplyingnamesofoneormorepackagesyouwanttodocument:
C:>javadocdC:\home\htmlsourcepathC:\home\srcjava.awtjava.awt.event
Case4RunfromanydirectoryonexplicitpackagesinmultipledirectorytreesThisisthesameascase3,butforpackagesinseparatedirectorytrees.Runjavadocsupplying
sourcepathwiththepathtoeachtree'sroot(colonseparated)andsupplynamesofoneormorepackagesyouwanttodocument.Allsourcefilesforagivenpackagedonotneedtobe
locatedunderasinglerootdirectorytheyjustneedtobefoundsomewherealongthesourcepath.
C:>javadocdC:\home\htmlsourcepathC:\home\src1C:\home\src2java.awtjava.awt.event
Result:AllcasesgenerateHTMLformatteddocumentationforthepublicandprotectedclassesandinterfacesinpackagesjava.awtandjava.awt.eventandsavetheHTMLfilesinthe
specifieddestinationdirectory(C:\home\html).Becausetwoormorepackagesarebeinggenerated,thedocumenthasthreeHTMLframesforthelistofpackages,thelistofclasses,and
themainclasspages.
DocumentingOneorMoreClasses
ThesecondwaytoruntheJavadoctoolisbypassinginoneormoresourcefiles(.java).Youcanrunjavadoceitherofthefollowingtwowaysbychangingdirectories(withcd)orbyfully
specifyingthepathtothe.javafiles.Relativepathsarerelativetothecurrentdirectory.Thesourcepathoptionisignoredwhenpassinginsourcefiles.Youcanusecommandline
wildcards,suchasasterisk(*),tospecifygroupsofclasses.
Case1ChangingtothesourcedirectoryChangetothedirectoryholdingthe.javafiles.Thenrunjavadoc,supplyingnamesofoneormoresourcefilesyouwanttodocument.
C:>cdC:\home\src\java\awt
C:>javadocdC:\home\htmlButton.javaCanvas.javaGraphics*.java
ThisexamplegeneratesHTMLformatteddocumentationfortheclassesButton,CanvasandclassesbeginningwithGraphics.Becausesourcefilesratherthanpackagenames
werepassedinasargumentstojavadoc,thedocumenthastwoframesforthelistofclassesandthemainpage.
Case2ChangingtothepackagerootdirectoryThisisusefulfordocumentingindividualsourcefilesfromdifferentsubpackagesoffthesameroot.Changetothepackageroot
directory,andsupplythesourcefileswithpathsfromtheroot.
C:>cdC:\home\src
C:>javadocd\home\htmljava\awt\Button.javajava\applet\Applet.java
ThisexamplegeneratesHTMLformatteddocumentationfortheclassesButtonandApplet.
Case3FromanydirectoryInthiscase,itdoesn'tmatterwhatthecurrentdirectoryis.Runjavadocsupplyingtheabsolutepath(orpathrelativetothecurrentdirectory)tothe.java
filesyouwanttodocument.
C:>javadocdC:\home\htmlC:\home\src\java\awt\Button.javaC:\home\src\java\awt\Graphics*.java
ThisexamplegeneratesHTMLformatteddocumentationfortheclassButtonandclassesbeginningwithGraphics.
DocumentingBothPackagesandClasses
Youcandocumententirepackagesandindividualclassesatthesametime.Here'sanexamplethatmixestwoofthepreviousexamples.Youcanusesourcepathforthepathtothe
packagesbutnotforthepathtotheindividualclasses.
C:>javadocdC:\home\htmlsourcepathC:\home\srcjava.awtC:\home\src\java\applet\Applet.java
ThisexamplegeneratesHTMLformatteddocumentationforthepackagejava.awtandclassApplet.(TheJavadoctooldeterminesthepackagenameforAppletfromthepackage
declaration,ifany,intheApplet.javasourcefile.)
REALWORLDEXAMPLE
TheJavadoctoolhasmanyusefuloptions,someofwhicharemorecommonlyusedthanothers.HereiseffectivelythecommandweusetoruntheJavadoctoolontheJavaplatformAPI.
Weuse180MBofmemorytogeneratethedocumentationforthe1500(approx.)publicandprotectedclassesintheJavaSEPlatform,StandardEdition,v1.2.
Thesameexampleisshowntwicefirstasexecutedonthecommandline,thenasexecutedfromamakefile.Itusesabsolutepathsintheoptionarguments,whichenablesthesame
javadoccommandtoberunfromanydirectory.
CommandLineExample
ThefollowingcommandlinemaybetoolongforsomeshellssuchasDOS.Youcanuseacommandlineargumentfile(orwriteashellscript)toworkaroundthislimitation.
C:\>javadocsourcepath\java\jdk\src\share\classes^
overview\java\jdk\src\share\classes\overview.html^
d\java\jdk\build\api^
use^
splitIndex^
windowtitle'JavaPlatform,StandardEdition7APISpecification'^
doctitle'JavaPlatform,StandardEdition7APISpecification'^
header'JavaSE7'^
bottom'<fontsize="1">
group"CorePackages""java.*:com.sun.java.*:org.omg.*"^
group"ExtensionPackages""javax.*"^
JXmx180m^
@packages
wherepackagesisthenameofafilecontainingthepackagestoprocess,suchasjava.appletjava.lang.Noneoftheoptionsshouldcontainanynewlinecharactersbetweenthe
singlequotes.(Forexample,ifyoucopyandpastethisexample,deletethenewlinecharactersfromthebottomoption.)Seetheothernoteslistedbelow.
MakefileExample
ThisisanexampleofaGNUmakefile.ForanexampleofaWindowsmakefile,seecreatingamakefileforWindows.
javadocsourcepath$(SRCDIR)^/*Setspathforsourcefiles*/
overview$(SRCDIR)\overview.html^/*Setsfileforoverviewtext*/
d\java\jdk\build\api^/*Setsdestinationdirectory*/
use^/*Adds"Use"files*/
splitIndex^/*SplitsindexAZ*/
windowtitle$(WINDOWTITLE)^/*Addsawindowtitle*/
doctitle$(DOCTITLE)^/*Addsadoctitle*/
header$(HEADER)^/*Addsrunningheadertext*/
bottom$(BOTTOM)^/*Addstextatbottom*/
group$(GROUPCORE)^/*1stsubheadonoverviewpage*/
group$(GROUPEXT)^/*2ndsubheadonoverviewpage*/
JXmx180m^/*Setsmemoryto180MB*/
java.langjava.lang.reflect^/*Setspackagestodocument*/
java.utiljava.iojava.net^
java.applet
WINDOWTITLE='JavaPlatform,StandardEdition6APISpecification'
DOCTITLE='JavaPlatform,StandardEdition6APISpecification'
HEADER='JavaPlatform,StandardEdition6'
BOTTOM='<fontsize="1">
GROUPCORE='"CorePackages""java.*:com.sun.java.*:org.omg.*"'
GROUPEXT='"ExtensionPackages""javax.*"'
SRCDIR='/java/jdk/1.7.0/src/share/classes'
Singlequotesareusedtosurroundmakefilearguments.
NOTES
Ifyouomitthewindowtitleoption,theJavadoctoolcopiesthedoctitletothewindowtitle.ThewindowtitletextisbasicallythesameasthedoctitlebutwithoutHTMLtags,to
preventthosetagsfromappearingasrawtextinthewindowtitle.
Ifyouomitthefooteroption,asdonehere,theJavadoctoolcopiestheheadertexttothefooter.
Otherimportantoptionsyoumightwanttousebutnotneededinthisexampleareclasspathandlink.
TROUBLESHOOTING
GeneralTroubleshooting
JavadocFAQCommonlyencounteredbugsandtroubleshootingtipscanbefoundontheJavadocFAQ
VersionnumberSeeversionnumbers.
DocumentsonlylegalclassesWhendocumentingapackage,javadoconlyreadsfileswhosenamesarecomposedoflegalclassnames.Youcanpreventjavadocfromparsingafile
byincluding,forexample,ahyphen""initsfilename.
ErrorsandWarnings
Errorandwarningmessagescontainthefilenameandlinenumbertothedeclarationlineratherthantotheparticularlineinthedoccomment.
"error:cannotread:Class1.java"theJavadoctoolistryingtoloadtheclassClass1.javainthecurrentdirectory.Theclassnameisshownwithitspath(absoluteorrelative),
whichinthiscaseisthesameas./Class1.java.
ENVIRONMENT
CLASSPATH
Environmentvariablethatprovidesthepathwhichjavadocusestofinduserclassfiles.Thisenvironmentvariableisoverriddenbytheclasspathoption.Separatedirectorieswitha
semicolon,forexample:
.C:\classesC:\home\java\classes
SEEALSO
javac
java
jdb
javah
javap
JavadocHomePage
HowtoWriteDocCommentsforJavadoc
SettingtheClassPath
HowJavacandJavadocFindClasses(tools.jar)
Copyright1993,2016,Oracleand/oritsaffiliates.Allrightsreserved. ContactUs

Javadoc-The Java API Documentation Generator

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Javadoc-The Java API Documentation Generator

Enviado por

Direitos autorais:

Formatos disponíveis

19/03/2017 javadocTheJavaAPIDocumentationGenerator

HowanameisdisplayedIflab elisomitted,thenpackage.class.memb erappears.Ingeneral,itissuitablyshortenedrelativetothecurrentclassandpackage.By

TypeofReference ExampleinString.toUpperCase() DisplaysAs

@seetagreferstomemberofthesameclass,samepackage @seeString#toLowerCase() toLowerCase()

@seetagreferstomemberofadifferentclass,samepackage @seeCharacter#toLowerCase(char) Character.toLowerCase(char)

@seetagreferstomemberofadifferentclass,differentpackage @seejava.io.File#exists() java.io.File.exists()

1.1 header private

Você também pode gostar