Manual Pages for UNIX Darwin command on man javadoc
MyWebUniversity

Manual Pages for UNIX Darwin command on man javadoc

javadoc(1) javadoc(1)





NAME
       javadoc - Java API documentation generator



SYNOPSIS
       jjaavvaaddoocc [ options ] [ packagenames ] [ sourcefilenames ] [ -ssuubbppaacckkaaggeess

       pkg1:pkg2:...  ] [ @argfiles ]

PPAARRAAMMEETTEERRSS
       Arguments can be in any order.


       options        Command-line options, as specified in this document.  To

                      see  a  typical  use  of jjaavvaaddoocc options, see Real World
                      Example.

       packagenames   A series of names of packages, separated by spaces, such

                      as jjaavvaa..llaanngg jjaavvaa..llaanngg..rreefflleecctt jjaavvaa..aawwtt.  You must sepa-

                      rately specify each package you want to  document.   The

                      JJaavvaaddoocc  tool uses -ssoouurrcceeppaatthh to look for these package

                      names.  The JJaavvaaddoocc tool does not  recursively  traverse
                      subpackages.   Wildcards  such  as asterisks (*) are not

                      allowed.  See EEXXAAMMPPLLEESS, Documenting One  or  More  Pack-

                      ages.

       sourcefilenames
                      A series of source file names, separated by spaces, each

                      of which can include paths and wildcards such as  aster-

                      isk (*).  The JJaavvaaddoocc tool will process every file whose
                      name ends with .java , and whose name, when stripped  of

                      that suffix, is actually a legal class name (see Identi-

                      fiers).  Therefore, you can name files with dashes (such

                      as  X-Buffer),  or  other illegal characters, to prevent

                      them from being documented.  This  is  useful  for  test
                      files and files generated from templates.  The path that
                      precedes the source file name determines  where  jjaavvaaddoocc
                      will  look  for the file.  The JJaavvaaddoocc tool does not use

                      -ssoouurrcceeppaatthh to look for these source file  names.)   For

                      example,  passing  in BBuuttttoonn..jjaavvaa is identical to ..//BBuutt-

                      ttoonn..jjaavvaa.  An example source file name with a full  path
                      is   //hhoommee//ssrrcc//jjaavvaa//aawwtt//GGrraapphhiiccss**..jjaavvaa.   See  EEXXAAMMPPLLEESS,

                      Documenting One or More Classes.  You can also mix pack-

                      agenames  and sourcefilenames, as in EEXXAAMMPPLLEESS, Document-

                      ing Both Packages and Classes.


       -ssuubbppaacckkaaggeess pkg1:pkg2:...

                      Generates documentation from source files in the  speci-

                      fied  packages  and recursively in their subpackages. An

                      alternative to  supplying  packagenames  or  sourcefile-

                      names.

       @argfiles      One  or  more  files  that  contain  a  list  of Javadoc
                      options, packagenames and sourcefilenames in any  order.

                      Wildcards  (*)  and  -JJ options are not allowed in these

                      files.


DESCRIPTION
       The JJaavvaaddoocc tool parses the declarations and documentation comments  in
       a  set  of  Java  source files and produces a corresponding set of HTML
       pages describing (by default) the public and protected classes,  nested
       classes  (but  not  anonymous inner classes), interfaces, constructors,
       methods, and fields.

       You can run the JJaavvaaddoocc tool  on  entire  packages,  individual  source
       files,  or  both.   In  the  first  case, you pass in as an argument to
       jjaavvaaddoocc a series of package names.  In the second case, you pass  in  a
       series  of  source (..jjaavvaa) file names.  See EEXXAAMMPPLLEESS at the end of this
       document.


              NNOOTTEE - When you pass in package names to the  Javadoc  tool,  it

              currently  processes  all ..jjaavvaa classes in the specified package
              directories, even if the ..jjaavvaa files are code examples or  other
              classes that are not actually members of the specified packages.
              It does not parse each ..jjaavvaa file for a package declaration;  we
              may add this parsing in a future release.


       During a run, the Javadoc tool automatically adds cross-reference links

       to package, class and member names that are being documented as part of
       that run. Links appear in several places:

       +o Declarations (return types, argument types, field types)

       +o "See Also" sections generated from @see tags


       +o In-line text generated from {@link} tags


       +o Exception names generated from @throws tags

       +o Specified  by  links  to members in interfaces and Overrides links to
         members in classes

       +o Summary tables listing packages, classes and members

       +o Package and class inheritance trees

       +o The index

       You can add hyperlinks to existing text for classes not included on the

       command  line  (but  generated  separately)  by  way  of  the -lliinnkk and

       -lliinnkkoofffflliinnee options.


       The Javadoc tool produces one complete document each time it is run; it

       cannot  do  incremental  builds - that is, it cannot modify or ddiirreeccttllyy

       incorporate results from previous runs of Javadoc. However, it can link
       to results from other runs, as just mentioned.


       As  implemented,  the JJaavvaaddoocc tool requires and relies on the java com-

       piler to do its job. The JJaavvaaddoocc tool calls part of  jjaavvaacc  to  compile
       the declarations, ignoring the member implementation.  It builds a rich
       internal representation of the classes, including the class  hierarchy,
       and "use" relationships, then generates the HTML from that. The JJaavvaaddoocc

       tool also picks up user-supplied documentation from documentation  com-

       ments in the source code.

       In  fact, the JJaavvaaddoocc tool will run on ..jjaavvaa source files that are pure

       stub files with no method bodies.  This means you can write  documenta-

       tion comments and run the JJaavvaaddoocc tool in the earliest stages of design
       while creating the API, before writing the implementation.

       Relying on the  compiler  ensures  that  the  HTML  output  corresponds
       exactly  with  the  actual  implementation, which may rely on implicit,
       rather than explicit, source code.  For example, the JJaavvaaddoocc tool  will

       document  default constructors (section 8.6.7 of Java Language Specifi-

       cation) that are present in the ..ccllaassss files  but  not  in  the  source
       code.

       In  many  cases,  the JJaavvaaddoocc tool allows you to generate documentation

       from source files whose code is incomplete or erroneous. This is a ben-

       efit  that  enables  you to generate documentation before all debugging

       and troubleshooting is done. For example, according to  the  Java  Lan-

       guage  Specification,  a  class that contains an abstract method should
       itself be declared abstract. The JJaavvaaddoocc tool does not check for  this,
       and  would  proceed without a warning, whereas the jjaavvaacc compiler stops
       on this error. The JJaavvaaddoocc tool does do some primitive checking of  doc

       comments.  Use the DocCheck doclet to check the doc comments more thor-

       oughly.


       When the JJaavvaaddoocc tool builds its internal structure for the  documenta-

       tion,  it  loads  all referenced classes.  Because of this, the JJaavvaaddoocc
       tool must be able to find all  referenced  classes,  whether  bootstrap
       classes,  extensions,  or  user  classes.  For more about this, see How
       Classes Are Found.  Generally speaking, classes you create must  either
       be loaded as an extension or in the JJaavvaaddoocc tool's class path.

   jjaavvaaddoocc DDoocclleettss
       You  can  customize the content and format of the JJaavvaaddoocc tool's output

       by using doclets. The JJaavvaaddoocc tool has  a  default  "built-in"  doclet,

       called  the standard doclet, that generates HTML-formatted API documen-

       tation.  You can modify or subclass the standard doclet, or write  your
       own  doclet  to  generate HTML, XML, MIF, RTF or whatever output format

       you'd like.  Information about doclets and their use is at the  follow-

       ing locations:


       +o JJaavvaaddoocc Doclets


       +o The -ddoocclleett command-line option



       When  a  custom  doclet  is not specified with the -ddoocclleett command line

       option, the JJaavvaaddoocc tool uses the default standard doclet.  The JJaavvaaddoocc
       tool  has several command line options that are available regardless of
       which doclet is being used.  The standard doclet adds  a  supplementary
       set  of command line options.  Both sets of options are described below
       in the options section.

   RReellaatteedd DDooccuummeennttaattiioonn aanndd DDoocclleettss
       +o Javadoc Enhancements for details about improvements added in  Javadoc
         1.4.

       +o Javadoc  FAQ  for  answers  to  common  questions,  information about

         Javadoc-related tools and workarounds for bugs.


       +o How to Write Doc Comments for Javadoc for more information about  Sun
         conventions for writing documentation comments.


       +o Requirements  for  Writing API Specifications - Standard requirements

         used when writing the Java 2 Platform Specification.  It can be  use-

         ful  whether  you are writing API specifications in source fiel docu-

         mentation comments or in  other formats.  It covers requirements  for
         packages,  classes, interfaces, fields and methods to stisfy testable
         assertions.


       +o Documentation Comments Specification - The original specification  on

         documentation  comments,  Chapter  18, Documentation Comments, in the
         Java Language Specification, First Edition, by  James  Gosling,  Bill

         Joy  and  Guy  Steele. (This chapter was removed from the second edi-

         tion.)


       +o DocCheck Doclet - Check doc comments in source files and generates  a

         report  listing the errors and irregularities it finds. It is part of
         the Sun Doc Check Utilities.


       +o MIF Doclet - Can automate the generation of API documentation in MIF,

         FrameMaker  and  PDF  formats.  MIF is Adobe FrameMaker's interchange
         format.

   TTeerrmmiinnoollooggyy
       A few terms have specific meanings within the context  of  the  JJaavvaaddoocc
       tool:

       generated document
                      The  document generated by the jjaavvaaddoocc tool from the doc
                      comments in Java source  code.   The  default  generated
                      document  is  in  HTML  and  is  created by the standard
                      doclet.


       name           A name in the Java Language, namely the name of a  pack-

                      age, class, interface, field, constructor, or method.  A

                      name     can     be     fully-qualified,     such     as

                      jjaavvaa..llaanngg..SSttrriinngg..eeqquuaallss((jjaavvaa..llaanngg..OObbjjeecctt)), or partially-

                      qualified, such as eeqquuaallss((OObbjjeecctt)).

       documented classes
                      The classes and interfaces for which full  documentation
                      is generated during a jjaavvaaddoocc run. To be documented, the
                      source files must be available, and either their  source
                      filenames  or  package  names  must  be  passed into the
                      jjaavvaaddoocc command.  We also refer to these as the  classes
                      included in the jjaavvaaddoocc run, or the included classes.

       inlcuded classes
                      Classes and interfaces whose source filenames or package
                      names are passed into the jjaavvaaddoocc command.

       excluded classes
                      Classes and interfaces whose source filename or  package
                      names are not passed into the jjaavvaaddoocc command.

       referenced classes
                      The  classes and interfaces that are explicitly referred
                      to in the definition (implementation) or doc comments of

                      the documented classes and interfaces.  Examples of ref-

                      erences include return type, parameter type, cast  type,
                      extended class, implemented interface, imported classes,
                      classes  used   in   method   bodies,   @see,   {@link},

                      {@linkplain}, and {@inheritDoc} tags.  (Notice this def-

                      inition has changed since 1.3.)  tags) do not qualify as
                      referenced  classes.   When  thE JJaavvaaddoocc tool is run, it
                      should load into memory all of the referenced classes in

                      javadoc's  bootclasspath  and  classpath.   (The Javadoc

                      tool prints a "Class not found" warning  for  referenced
                      classes  not found.)  The JJaavvaaddoocc tool can derive enough
                      information from the ..ccllaassss  files  to  determine  their

                      existence  and  the  fully qualified names of their mem-

                      bers.

       external referenced classes
                      The referenced classes  whose  documentation  not  being
                      generated  during  a jjaavvaaddoocc run.  In other words, these
                      classes are not passed into  the  JJaavvaaddoocc  tool  on  the

                      comand  line.  Links for names in the generated documen-

                      tation to those classes are said to be  external  refer-

                      ences  or  external  links.  For example, if you run the
                      JJaavvaaddoocc tool on only  the  jjaavvaa..aawwtt  package,  then  any

                      class  in jjaavvaa..llaanngg, such as Object, is an external ref-

                      erenced  class.   External  referenced  classes  can  be

                      linked  to using the -lliinnkk and -lliinnkkoofffflliinnee options.  An

                      important property of an external  referenced  class  is
                      that  its  source comments are normally not available to
                      the JJaavvaaddoocc run. In this case, these comments cannot  be
                      inherited.

   SSoouurrccee FFiilleess
       The  JJaavvaaddoocc  tool will generate output originating from four different
       types of  "source"  files:  Java  language  source  files  for  classes

       (..jjaavvaa),  package  comment files, overview comment files, and miscella-

       neous unprocessed files.

   CCllaassss SSoouurrccee CCooddee FFiilleess

       Each class or interface and its members can have their  own  documenta-

       tion  comment, contained in a ..jjaavvaa file.  For more details about these
       doc commments, see DDooccuummeennttaattiioonn CCoommmmeennttss below.

   PPaacckkaaggee CCoommmmeenntt FFiilleess
       Each package can have its own documentation comment, contained  in  its
       own  "source"  file,  that the JJaavvaaddoocc tool will merge into the package
       summary page that it generates.  You typically include in this  comment
       any documentation that applies to the entire package.

       To  create  a  package  comment file, you must name it ppaacckkaaggee..hhttmmll and
       place it in the package directory in the source  tree  along  with  the
       ..jjaavvaa files. The JJaavvaaddoocc tool will automatically look for this filename

       in this location.  Notice that the filename is identical for all  pack-

       ages. For explicit details, see the example of package.html.


       The  content  of the package comment file is one big documentation com-

       ment, written in HTML, like all other comments, with one exception: The
       documentation comment should not include the comment separators /** and
       */ or leading asterisks.  When writing the comment, you should make the
       first  sentence a summary about the package, and not put a title or any
       other text between <> and the  first  sentence.   You  can  include
       package  tags;  as  with  any  documentation  comment,  all tags except
       {@@lliinnkk} must appear after the description.  If you add a @@sseeee tag in  a
       package comment file, it must have a fully qualified name.

       When  the  JJaavvaaddoocc  tool runs, it automatically looks for this file; if
       found, the JJaavvaaddoocc tool does the following:


       +o Copies all content between <> and <> tags for processing.

       +o Processes any package tags that are present.

       +o Inserts the processed text at the bottom of the package summary  page
         it generates, as shown in Package Summary.

       +o Copies  the  first  sentence of the package comment to the top of the
         package summary page.  It also adds the package name and  this  first
         sentence  to  the  list of packages on the overview page, as shown in

         Overview Summary.  The end-of-sentence  is  determined  by  the  same

         rules  used  for  the  end  of the first sentence of class and member
         descriptions.

   OOvveerrvviieeww CCoommmmeenntt FFiillee
       Each application or set of packages that you are documenting  can  have
       its  own overview documentation comment, kept in its own "source" file,

       that the JJaavvaaddoocc tool will merge into the overview page that it  gener-

       ates.   You  typically  include  in this comment any documentation that
       applies to the entire application or set of packages.

       To create an overview comment file, you can name the file anything  you
       want,  typically oovveerrvviieeww..hhttmmll, and place it anywhere, typically at the

       top level of the source tree.  Notice that you can have multiple  over-

       view  comment  files for the same set of source files, in case you want

       to run jjaavvaaddoocc multiple times on different sets of packages.  For exam-

       ple,  if  the source files for the jjaavvaa..aapppplleett package are contained in

       //hhoommee//uusseerr//ssrrcc//jjaavvaa//aapppplleett directory, you could create an overview com-

       ment file at //hhoommee//uusseerr//ssrrcc//oovveerrvviieeww..hhttmmll.


       The  content of the overview comment file is one big documentation com-

       ment, written in HTML, like the package comment file  described  previ-

       ously.   See  that description for details.  To reiterate, when writing
       the comment, you should make the first sentence  a  summary  about  the
       application  or  set of packages, and not put a title or any other text
       between <> and the first sentence.  You can include overview  tags;
       as  with any documentation comment, all tags except {@@lliinnkk} must appear

       after the description.  If you add a @@sseeee tag, it must  have  a  fully-

       qualified name.

       When  you  run  the JJaavvaaddoocc tool, you specify the overview comment file

       name with the -oovveerrvviieeww option.  The file is then processed, similar to

       that of a package comment file:

       +o Copies all content between <> and <> tags for processing.

       +o Processes any overview tags that are present.


       +o Inserts the processed text at the bottom of the overview page it gen-

         erates, as shown in Overview Summary.

       +o Copies the first sentence of the overview comment to the top  of  the
         overview summary page.

   MMiisscceellllaanneeoouuss UUnnpprroocceesssseedd FFiilleess
       You  can  also  include in your source any miscellaneous files that you

       want the JJaavvaaddoocc tool to copy to the destination directory.  These typ-

       ically  include  graphic  files  (for  example, Java source (..jjaavvaa) and

       class (..ccllaassss) files) and self-standing HTML files whose content  would

       overwhelm the documentation comment of a normal Java source file.


       To include unprocessed files, put them in a directory called ddoocc-ffiilleess,

       which can be a subdirectory of any package directory.  You can have one
       such  subdirectory for each package.  You might include images, example

       code, source files, ..ccllaassss files, applets, and HTML files.   For  exam-

       ple,  if  you  want  to include the image of a button bbuuttttoonn..ggiiff in the
       jjaavvaa..aawwtt..BBuuttttoonn  class  documentation,  you  place  that  file  in  the

       //hhoommee//uusseerr//ssrrcc//jjaavvaa//aawwtt//ddoocc-ffiilleess//  directory.   Notice  the  ddoocc-ffiilleess

       directory  should  not  be  located  at   //hhoommee//uusseerr//ssrrcc//jjaavvaa//ddoocc-ffiilleess

       because  jjaavvaa  is not a package - that is, it does not directly contain

       any source files.


       All links to these unprocessed files must be  hard-coded,  because  the

       JJaavvaaddoocc  tool  does not look at the files - it simply copies the direc-

       tory and all its contents to the destination.  For example, the link in
       the BBuuttttoonn..jjaavvaa doc comment might look like:

       //****
       ** TThhiiss bbuuttttoonn llooookkss lliikkee tthhiiss::

       ** <>

       **//

TTeesstt FFiilleess aanndd TTeemmppllaattee FFiilleess

       Some  developers  have indicated they want to store test files and tem-

       plates files in the source tree near their corresponding source  files.

       That is, they would like to put them in the same directory, or a subdi-

       rectory, of those source files.


       If you run the Javadoc tool by explicitly passing in individual source-

       filenames,  you  can deliberately omit test and templates files andpre-

       vent them from being processed. However, if you are passing in  package
       names  or  wildcards,  you  need to follow certain rulesto ensure these
       test files and templates files are not processed.


       Test files differ from template files in that the former arelegal, com-

       pilable  source  files,  while  the  latter  are  not, but may end with
       ".java".


       TTeesstt ffiilleess -

              Often developers want to put compilable, runnable test files for
              a  given  package  in the same directory as the source files for

              that package.  But they want the test files to belong to a pack-

              age  other  than  the  source  file package, such as the unnamed
              package (so test files have no package statement or a  different
              package  statement  from the source). In this scenario, when the

              source is being documented by specifying its package name speci-

              fied  on the command line, the test files will cause warnings or
              errors. You need to put such test files in a  subdirectory.  For
              example,  if  you  want  to  add  test files for source files in
              ccoomm..ppaacckkaaggee11 put them in a subdirectory that would be an invalid
              package name (because it contains a hyphen):


            com/package1/test-files/



       The  test  directory  will be skipped by the Javadoc tool with no warn-

       ings.

       If your test files contain doc comments, you can set up a separate  run

       of the Javadoc tool to produce documentation of the test files by pass-

       ing in their test source filenames with wildcards,  such  as  ccoomm//ppaacckk-

       aaggee//   eesstt-ffiilleessjjaavvaa ..



       Tempaltes for source files -

              Template  files have names that often end in ".java" and are not
              compilable. If you have a template for a source  file  that  you
              want  to  keep  in  the source directory, you can name it with a

              dash (such as Buffer-Template.java ), or any other illegal  Java

              character,  to  prevent  it from being processed. This relies on
              the fact that the Javadoc tool  will  only  process  sourcefiles
              whose  name,  when stripped of the ".java" suffix, is actually a
              legal class name (see Identifiers ).

   GGeenneerraatteedd FFiilleess

       By default, jjaavvaaddoocc uses a standard doclet that generates  HTML-format-

       ted  documentation.  This doclet generates the following kinds of files
       (where each HTML "page" corresponds to a  separate  file).   Note  that
       jjaavvaaddoocc  generates  files  with  two  types of names: those named after

       classes/interfaces, and  those  that  are  not  (such  as  ppaacckkaaggee-ssuumm-

       mmaarryy..hhttmmll).   Files in the latter group contain hyphens to prevent file
       name conflicts with those in the former group.

   BBaassiicc CCoonntteenntt PPaaggeess

       +o One class or interface page (ccllaassssnnaammee..hhttmmll) for each class or inter-

         face it is documenting.


       +o One  package page (ppaacckkaaggee-ssuummmmaarryy..hhttmmll) for each package it is docu-

         menting. The JJaavvaaddoocc tool includes any HTML text provided in  a  file
         named ppaacckkaaggee..hhttmmll in the package directory of the source tree.


       +o One overview page (oovveerrvviieeww-ssuummmmaarryy..hhttmmll) for the entire set of pack-

         ages.  This is the front page of the generated document.  The JJaavvaaddoocc
         tool  includes  any  HTML  text provided in a file specified with the

         -oovveerrvviieeww option.  Note that this file is created only  if  you  pass

         into jjaavvaaddoocc two or more package names.  For further explanation, see
         HHTTMMLL FFrraammeess below.


   CCrroossss-RReeffeerreennccee PPaaggeess

       +o One class hierarchy page for the entire set  of  packages  (oovveerrvviieeww-

         ttrreeee..hhttmmll).  To view this, click on "Overview" in the navigation bar,
         then click on "Tree".


       +o One class hierarchy page for each  package  (ppaacckkaaggee-ttrreeee..hhttmmll).   To

         view this, go to a particular package, class or interface page; click
         "Tree" to display the hierarchy for that package.


       +o One "use" page for each package (ppaacckkaaggee-uussee..hhttmmll) and a separate one

         for  each  class  and interface (ccllaassss-uussee//ccllaassssnnaammee..hhttmmll). This page

         describes what packages, classes, methods, constructors,  and  fields
         use  any  part  of  the  given class, interface, or package.  Given a
         class or interface A, its "use" page includes subclasses of A, fields
         declared  as  A,  methods that return A, and methods and constructors
         with parameters of type A.  You can access this page by  first  going
         to  the package, class, or interface, then clicking on the "Use" link
         in the navigation bar.


       +o A deprecated API page (ddeepprreeccaatteedd-lliisstt..hhttmmll) listing  all  deprecated

         names.   (A deprecated name is not recommended for use, generally due
         to improvements, and a replacement name is usually given.  Deprecated
         APIs may be removed in future implementations.)


       +o A constant field values page (ccoonnssttaanntt-vvaalluueess..hhttmmll) for the values of

         static fields.


       +o A serialized form page (sseerriiaalliizzeedd-ffoorrmm..hhttmmll) for  information  about

         serializable  and  externalizable  classes.   Each  such  class has a

         description of its serialization fields and methods.   This  informa-

         tion  is  of interest to re-implementors, not to developers using the

         API.  While there is no link in the navigation bar, you  can  get  to

         this information by going to any serialized class and clicking "Seri-

         alized Form" in the "See also" section of the class description.  The
         standard  doclet  automatically generates a serialized form page: any

         class  (public  or  non-public)  that  implements   Serializable   is

         included,  along  with rreeaaddOObbjjeecctt and wwrriitteeOObbjjeecctt methods, the fields

         that are serialized, and the doc comments from the @serial,  @serial-

         Field,  and  @serialData  tags.  Public  serializable  classes can be
         excluded by marking them (or their package) with @serial exclude, and

         package-private  serializable classes can be included by marking them

         (or their package) with @serial include. As of 1.4, you can  generate

         the  complete  serialized form for public and private classes by run-

         ning javadoc without specifying the -pprriivvaattee option.



       +o An index (iinnddeexx-**..hhttmmll) of all class, interface,  constructor,  field

         and method names, alphabetically arranged.  This is internationalized
         for Unicode and can be generated as a single file or  as  a  separate

         file for each starting character (such as A-Z for English).


   SSuuppppoorrtt FFiilleess

       +o A help page (hheellpp-ddoocc..hhttmmll) that describes the navigation bar and the

         above pages.  You can provide your own custom help file  to  override

         the default using -hheellppffiillee.


       +o One  iinnddeexx..hhttmmll  file that creates the HTML frames for display.  This
         is the file you load to display the front  page  with  frames.   This
         file itself contains no text content.


       +o Several  frame  files  (**-ffrraammee..hhttmmll)  containing  lists of packages,

         classes and interfaces, used when HTML frames are being displayed.


       +o A package list file (ppaacckkaaggee-lliisstt), used by the  -lliinnkk  and  -lliinnkkooff-

         fflliinnee  options.   This is a text file, not HTML, and is not reachable
         through any links.

       +o A style sheet file (ssttyylleesshheeeett..ccssss) that controls a limited amount of
         color,  font  family,  font  size, font style, and positioning on the
         generated pages.


       +o A doc-files directory that holds any image, example, source code,  or

         other files that you want copied to the destination directory.  These
         files are not processed by the JJaavvaaddoocc tool in any manner,  that  is,

         any jjaavvaaddoocc tags in them will be ignored.  This directory is not gen-

         erated unless it exists in the source tree.

   HHTTMMLL FFrraammeess
       The JJaavvaaddoocc tool will generate either two  or  three  HTML  frames,  as
       shown  in  the  figure below.  When you pass source files (*..jjaavvaa) or a
       single package name as arguments into the jjaavvaaddoocc command,  it  creates

       only  one  frame  (C)  in  the  left-hand  column, that is, the list of

       classes.  When you pass into jjaavvaaddoocc two or more package names, it cre-

       ates  a  third  frame  (P) listing all packages, as well as an overview

       page (Detail).  This overview page has  the  file  name,  oovveerrvviieeww-ssuumm-

       mmaarryy..hhttmmll.   Thus, this file is created only if you pass in two or more
       package names.  You can bypass frames by clicking on  the  "No  Frames"

       link or entering at oovveerrvviieeww-ssuummmmaarryy..hhttmmll.


       If you are unfamiliar with HTML frames, you should be aware that frames
       can have focus for printing and scrolling.   To  give  a  frame  focus,
       click  on it.  Then, on many browsers the arrow keys and page keys will
       scroll that frame, and the print menu command will print it.


           ------------                  ------------

           ||CC|| DDeettaaiill ||                  ||PP|| DDeettaaiill ||
           || ||        ||                  || ||        ||

           || ||        ||                  ||-||        ||

           || ||        ||                  ||CC||        ||
           || ||        ||                  || ||        ||
           || ||        ||                  || ||        ||

           ------------                  ------------

          jjaavvaaddoocc **..jjaavvaa           jjaavvaaddoocc jjaavvaa..llaanngg jjaavvaa..aawwtt

       Load one of the following two files as the starting page  depending  on
       whether you want HTML frames or not:


       +o iinnddeexx..hhttmmll (for frames)


       +o oovveerrvviieeww-ssuummmmaarryy..hhttmmll (for no frames)


   GGeenneerraatteedd FFiillee SSttrruuccttuurree
       The  generated  class  and  interface  files  are organized in the same

       directory hierarchy as Java source files and class files.  This  struc-

       ture is one directory per subpackage.

       For  example,  the  document generated for the class jjaavvaa..aapppplleett..AApppplleett
       would be located at jjaavvaa//aapppplleett//AApppplleett..hhttmmll.  The  file  structure  for
       the  jjaavvaa..aapppplleett  package follows, given that the destination directory
       is named aappiiddooccss.  All files that contain the word  "frame"  appear  in

       the  upper-left  or  lower-left frames, as noted.  All other HTML files

       appear in the right-hand frame.



       NOTE: Directories are shown in bold.  The asterisks  (*)  indicate  the

       files  and  directories  that are omitted when the arguments to jjaavvaaddoocc
       are source file names (*..jjaavvaa) rather than package names.   Also,  when

       arguments  are source file names, ppaacckkaaggee-lliisstt is created but is empty.

       The ddoocc-ffiilleess directory is not created in  the  destination  unless  it

       exists in the source tree.



       aappiiddooccss                         TToopp ddiirreeccttoorryy
         iinnddeexx..hhttmmll                    IInniittiiaall ppaaggee tthhaatt sseettss uupp HHTTMMLL ffrraammeess

       ** oovveerrvviieeww-ssuummmmaarryy..hhttmmll         LLiissttss aallll ppaacckkaaggeess wwiitthh ffiirrsstt sseenntteennccee ssuummmmaarriieess

         oovveerrvviieeww-ttrreeee..hhttmmll            LLiissttss ccllaassss hhiieerraarrcchhyy ffoorr aallll ppaacckkaaggeess

         ddeepprreeccaatteedd-lliisstt..hhttmmll          LLiissttss ddeepprreeccaatteedd AAPPII ffoorr aallll ppaacckkaaggeess

         ccoonnssttaanntt-vvaalluueess..hhttmmll          LLiissttss vvaalluueess ooff ssttaattiicc ffiieellddss ffoorr aallll ppaacckkaaggeess



         sseerriiaalliizzeedd-ffoorrmm..hhttmmll          LLiissttss sseerriiaalliizzeedd ffoorrmm ffoorr aallll ppaacckkaaggeess

       ** oovveerrvviieeww-ffrraammee..hhttmmll           LLiissttss aallll ppaacckkaaggeess,, uusseedd iinn uuppppeerr-lleefftt ffrraammee

         aallllccllaasssseess-ffrraammee..hhttmmll         LLiissttss aallll ppaacckkaaggee ccllaasssseess,, lloowweerr-lleefftt ffrraammee

         hheellpp-ddoocc..hhttmmll                 LLiissttss uusseerr hheellpp ffoorr hhooww ppaaggeess aarree oorrggaanniizzeedd

         iinnddeexx-aallll..hhttmmll                DDeeffaauulltt iinnddeexx ccrreeaatteedd ww//oo -sspplliittiinnddeexx ooppttiioonn

         iinnddeexx-ffiilleess                   DDiirreeccttoorryy ccrreeaatteedd wwiitthh -sspplliittiinnddeexx ooppttiioonn

            iinnddeexx-<>..hhttmmll        IInnddeexx ffiilleess ccrreeaatteedd wwiitthh -sspplliittiinnddeexx ooppttiioonn

         ppaacckkaaggee-lliisstt                  LLiissttss ppaacckkaaggee nnaammeess uusseedd oonnllyy ffoorr rreessoollvviinngg eexxtteerrnnaall rreeffss

         ssttyylleesshheeeett..ccssss                HHTTMMLL ssttyyllee sshheeeett ffoorr ddeeffiinniinngg ffoonnttss,, ccoolloorrss,, ppoossiittiioonnss
         jjaavvaa                          PPaacckkaaggee ddiirreeccttoorryy
            aapppplleett                     SSuubbppaacckkaaggee ddiirreeccttoorryy
               AApppplleett..hhttmmll             PPaaggee ffoorr AApppplleett ccllaassss
               AApppplleettCCoonntteexxtt..hhttmmll      PPaaggee ffoorr AApppplleettCCoonntteexxtt iinntteerrffaaccee
               AApppplleettSSttuubb..hhttmmll         PPaaggee ffoorr AApppplleettSSttuubb iinntteerrffaaccee
               AAuuddiiooCClliipp..hhttmmll          PPaaggee ffoorr AAuuddiiooCClliipp iinntteerrffaaccee

             ** ppaacckkaaggee-ssuummmmaarryy..hhttmmll    LLiissttss ccllaasssseess wwiitthh ffiirrsstt sseenntteennccee ssuummmmaarriieess

             ** ppaacckkaaggee-ffrraammee..hhttmmll      LLiissttss ppaacckkaaggee ccllaasssseess,, lloowweerr lleefftt-hhaanndd ffrraammee

             ** ppaacckkaaggee-ttrreeee..hhttmmll       LLiissttss ccllaassss hhiieerraarrcchhyy ffoorr tthhiiss ppaacckkaaggee

               ppaacckkaaggee-uussee             LLiissttss wwhheerree tthhiiss ppaacckkaaggee iiss uusseedd

               ddoocc-ffiilleess               DDiirreeccttoorryy hhoollddiinngg iimmaaggee && eexxaammppllee ffiilleess

               ccllaassss-uussee               DDiirreeccttoorryy hhoollddiinngg ppaaggeess AAPPII iiss uusseedd

                  AApppplleett..hhttmmll          PPaaggee ffoorr uusseess ooff AApppplleett ccllaassss
                  AApppplleettCCoonntteexxtt..hhttmmll   PPaaggee ffoorr uusseess ooff AApppplleettCCoonntteexxtt iinntteerrffaaccee
                  AApppplleettSSttuubb..hhttmmll      PPaaggee ffoorr uusseess ooff AApppplleettSSttuubb iinntteerrffaaccee
                  AAuuddiiooCClliipp..hhttmmll       PPaaggee ffoorr uusseess ooff AAuuddiiooCClliipp iinntteerrffaaccee

         ssrrcc-hhttmmll                      SSoouurrccee ccooddee ddiirreeccttoorryy

            jjaavvaa                       PPaacckkaaggee ddiirreeccttoorryy
               aapppplleett                  SSuubbppaacckkaaggee ddiirreeccttoorryy
                  AApppplleett..hhttmmll          PPaaggee ffoorr AApppplleett ssoouurrccee ccooddee
                  AApppplleettCCoonntteexxtt..hhttmmll   PPaaggee ffoorr AApppplleettCCoonntteexxtt ssoouurrccee ccooddee
                  AApppplleettSSttuubb..hhttmmll      PPaaggee ffoorr AApppplleettSSttuubb ssoouurrccee ccooddee
                  AAuuddiiooCClliipp..hhttmmll       PPaaggee ffoorr AAuuddiiooCClliipp ssoouurrccee ccooddee

   GGeenneerraatteedd AAPPII DDeeccllaarraattiioonnss
       The  JJaavvaaddoocc  tool  generates a declaration at the start of each class,
       interface, field, constructor, and method description. This declaration
       is  the declaration for that API item. For example, the declaration for
       the Boolean class is:

              ppuubblliicc ffiinnaall ccllaassss BBoooolleeaann
              eexxtteennddss OObbjjeecctt
              iimmpplleemmeennttss SSeerriiaalliizzaabbllee

       and the declaration for the Boolean.valueOf method is:

              ppuubblliicc ssttaattiicc BBoooolleeaann vvaalluueeOOff((SSttrriinngg ss))

       The JJaavvaaddoocc tool can include the modifiers ppuubblliicc,, pprrootteecctteedd,,  pprriivvaattee,,
       aabbssttrraacctt,,  ffiinnaall,, ssttaattiicc,, ttrraannssiieenntt,, and vvoollaattiillee,, but not ssyynncchhrroonniizzeedd
       or nnaattiivvee..  These last  two  modifiers  are  considered  implementation
       detail and not part of the API specification.

       Rather  than  relying on the keyword ssyynncchhrroonniizzeedd,, APIs should document
       their concurrency semantics in the comment description, as in "a single

       EEnnuummeerraattiioonn cannot be used by multiple threads concurrently".  The doc-

       ument should not describe how to achieve these  semantics.  As  another

       example,  while  HHaasshhttaabbllee  should be thread-safe, there's no reason to

       specify that we achieve this by synchronizing all of its exported meth-

       ods.  We  should  reserve  the  right  to synchronize internally at the
       bucket level, thus offering higher concurrency.


   DDooccuummeennttaattiioonn CCoommmmeennttss
       The original "Documentation Comments Specification" can be found  under
       related documentation.

   CCoommmmeennttiinngg tthhee SSoouurrccee CCooddee
       You  can  include documentation comments ("doc comments") in the source

       code, ahead of declarations for any entity (classes, interfaces,  meth-

       ods,  constructors,  or  fields).  You can also create doc comments for
       each package and another one for the overview, though their  syntax  is
       slightly  different.   Doc comments are also known as Javadoc comments.
       A doc comment consists of the characters  between  the  characters  //****
       that  begin  the  comment  and  the characters **// that end it.  Leading
       asterisks are allowed on each line and  are  described  further  below.
       The text can continue onto multiple lines.

              //****
              ** TThhiiss iiss tthhee ttyyppiiccaall ffoorrmmaatt ooff aa ssiimmppllee ddooccuummeennttaattiioonn ccoommmmeenntt
              ** tthhaatt ssppaannss ttwwoo lliinneess..
              **//

       To save space you can put a comment on one line:

              //**** TThhiiss ccoommmmeenntt ttaakkeess uupp oonnllyy oonnee lliinnee.. **//


       Placement of comments - Documentation comments are recognized only when

       placed immediately before class,  interface,  constructor,  method,  or
       field  declarations  (see  the class example, method example, and field
       example).  Documentation comments placed in the body of  a  method  are
       ignored.   Only  one documentation comment per declaration statement is
       recognized by the JJaavvaaddoocc tool.


       A common mistake is to put an import statement between the  class  com-

       ment and the class declaration.  Avoid this, as jjaavvaaddoocc will ignore the
       class comment.

              //****
              ** TThhiiss iiss tthhee ccllaassss ccoommmmeenntt ffoorr tthhee ccllaassss WWhhaatteevveerr..
              **//


              iimmppoorrtt ccoomm..ssuunn;;   //// MMIISSTTAAKKEE - IImmppoorrttaanntt nnoott ttoo ppuutt ssttaatteemmeenntt hheerree


              ppuubblliicc ccllaassss WWhhaatteevveerr {{
              }}


       A comment is a description followed by tags -  The  description  begins

       after  the  starting delimiter //**** and continues until the tag section.
       The tag section starts with the first character @@ that  begins  a  line
       (ignoring leading asterisks and white space).  It is possible to have a

       comment with only tags and no description.  The description cannot con-

       tinue  after  the  tag  section begins.  The argument to a tag can span

       multiple lines.  There can be any number of tags - some types  of  tags

       can be repeated while others cannot.  This @@sseeee starts the tag section:

               //****
               ** TThhiiss iiss aa ddoocc ccoommmmeenntt..
               ** @@sseeee jjaavvaa..llaanngg..OObbjjeecctt
               **//


       Standard and in-line tags - A ttaagg is a special  keyword  within  a  doc

       comment that the Javadoc tool can process.  The Javadoc tool has stand-

       alone tags, which appear as @@ttaagg,, and in-line tags, which appear within

       braces,  as {{@@ttaagg}.  To be interpreted, a standalone tag must appear at
       the beginning of a line, ignoring leading asterisks,  white  space  and

       comment  separator (/**).  This means you can use the @ character else-

       where in the text and it will not be interpreted as the start of a tag.
       If  you  want  to  start a line with the @ character and not have it be

       interpreted, use the HTML entity @.  Each standalone tag has asso-

       ciated  text,  which includes any text following the tag up to, but not
       including, either the next tag, or the end of  the  doc  comment.  This

       associated text can span multiple lines.  An in-line tag is allowed and

       interpreted anywhere that text is allowed. The following  example  con-

       tains the standalone tag @@ddeepprreeccaatteedd and in-line tag {{@@lliinnkk}}..


              //****

               ** @@ddeepprreeccaatteedd AAss ooff JJDDkk 11..11,, rreeppllaacceedd bbyy {{@@lliinnkk ##sseettBBoouunnddss((iinntt,,iinntt,,iinntt,,iinntt))}}

               **//


       Comments  are  written  in  HTML - The text must be written in HTML, in

       that they should use HTML entities and HTML tags.  You can  use  which-

       ever  version  of HTML your browser supports; we have written the stan-

       dard doclet to generate HTML 3.2-compliant code elsewhere  (outside  of

       the  documentation  comments)  with  the  inclusion  of cascading style
       sheets and frames.  (We preface each generated  file  with  "HTML  4.0"
       because of the frame sets.)


       For  example,  entities for the less-than (<) and greater-than (>) sym-

       bols should be written &&lltt;; and  &&ggtt;;.   Likewise,  the  ampersand  (&)

       should be written &&aammpp;;.  The bold HTML tag  is shown in the follow-

       ing example:

              //****
              ** TThhiiss iiss aa <>ddoocc<> ccoommmmeenntt..
              ** @@sseeee jjaavvaa..llaanngg..OObbjjeecctt
              **//


       Leading asterisks - When jjaavvaaddoocc parses a doc comment, leading asterisk

       (*)  characters  on  each line are discarded; blanks and tabs preceding
       the initial asterisk (*) characters are also discarded.   If  you  omit
       the  leading  asterisk  on  a line, all leading white space is removed.
       Therefore, you should not omit leading asterisks if  you  want  leading
       white  space  to  be  kept, such as when indenting sample code with the
       <> tag.


       First sentence - The first sentence of each doc  comment  should  be  a

       summary  sentence, containing a concise but complete description of the

       declared entity.  This sentence ends at the first period that  is  fol-

       lowed  by  a blank, tab, or line terminator, or at the first standalone
       tag. The JJaavvaaddoocc tool copies this first sentence to the member  summary
       at the top of the HTML page.


       Declaration  with  multiple  fields  -  JJaavvaa  allows declaring multiple

       fields in a single statement, but this statement can have only one doc-

       umentation  comment, which is copied for all fields.  Therefore, if you
       want individual documentation comments for each field, you must declare

       each  field  in a separate statement.  For example, the following docu-

       mentation comment doesn't make sense when written as a single  declara-

       tion and would be better handled as two declarations:

              //****
              * The horizontal and vertical distances of point (x,y)              **//
              ppuubblliicc iinntt xx,, yy;;      //// AAvvooiidd tthhiiss

       The  JJaavvaaddoocc  tool generates the following documentation from the above
       code:

              ppuubblliicc iinntt xx
              The horizontal and vertical distances of point (x,y).
              ppuubblliicc iinntt yy
              The horizontal and vertical distances of point (x,y).


       Use header tags carefully - When  writing  documentation  comments  for

       members, it is best not to use HTML heading tags such as <> and <>,
       because the JJaavvaaddoocc tool creates  an  entire  structured  document  and

       these  structural  tags can interfere with the formatting of the gener-

       ated document.  However, it is fine to use these headings in class  and
       package comments to provide your own structure.


   Automatic Reuse of Method Comments       The  JJaavvaaddoocc  tool  has the ability to automatically reuse or "inherit"
       method comments in classes  and  interfaces.  When  a  description,  or
       @return,  @param, @see or @throws tag is missing from a method comment,
       the JJaavvaaddoocc tool instead copies the corresponding  description  or  tag
       comment  from the method it overrides or implements (if any), according
       to the algorithm below.

       More specifically, when a @param tag  for  a  particular  parameter  is
       missing,  then  the  comment  for  that  parameter  is copied.  When an
       @throws tag for a particular exception is missing, the @throws  tag  is
       copied only if that exception is declared.


       This  behavior  contrasts with version 1.3 and earlier, where the pres-

       ence of any description or tag would prevent all  comments  from  being
       inherited.

       Also  of  interest,  is  the  inline  tag {@@iinnhheerriittDDoocc} is present in a
       description or any tag, the corresponding description or tag is  copied
       at that spot.

       The  overridden  method must be a member of a documented class, and not

       an external referenced class for the doc comment to actually be  avail-

       able to copy.

       Inheriting of comments occurs in three cases:

       +o When a method in a class overrides a method in a superclass
       +o When a method in an interface overrides a method in a superinterface
       +o When a method in a class implements a method in an interface


       In  the  first two cases, for method overrides, the JJaavvaaddoocc tool gener-

       ates a subheading "Overrides" in the documentation for  the  overriding
       method, with a link to the method it is overriding.

       In  the  third case, when a method in a given class implements a method
       in an interface, the JJaavvaaddoocc tool generates a subheading "Specified by"
       in  the  documentation  for  the  overriding method, with a link to the
       method it is implementing.

       Algorithm for Inheriting Method Descriptions If a method does not  have
       a  doc  comment,  the  JJaavvaaddoocc  tool searches for an applicable comment

       using the following algorithm, which is designed to find the most  spe-

       cific  applicable  doc  comment,  giving  preference to interfaces over
       superclasses:

       1.  Look in each directly implemented (or extended)  interface  in  the
           order they appear following the word implements (or extends) in the
           method declaration. Use  the  first  doc  comment  found  for  this
           method.

       2.  If  step  1  failed  to  find a doc comment, recursively apply this

           entire algorithm to each directly implemented (or extended)  inter-

           face, in the same order they were examined in step 1.

       3. If step 2 failed to find a doc comment and this is
           a class other than Object (not an interface):

           aa.. IIff tthhee ssuuppeerrccllaassss hhaass aa ddoocc ccoommmmeenntt ffoorr tthhiiss mmeetthhoodd,, uussee iitt..
           bb.. IIff sstteepp 33aa ffaaiilleedd ttoo ffiinndd aa ddoocc ccoommmmeenntt,, rreeccuurrssiivveellyy aappppllyy tthhiiss
           eennttiirree aallggoorriitthhmm ttoo tthhee ssuuppeerrccllaassss..


   jjaavvaaddoocc TTaaggss
       The  JJaavvaaddoocc  tool  parses special tags when they are embedded within a

       Java doc comment.  These doc tags enable you  to  autogenerate  a  com-

       plete,  well-formatted  API from your source code.  The tags start with

       an "at" sign (@@) and are case-sensitive - they must be typed  with  the

       uppercase  and  lowercase  letters  as  shown.  A tag must start at the
       beginning of a line (after any leading spaces and an optional asterisk)
       or  it  is  treated  as normal text.  By convention, tags with the same
       name are grouped together.  For example, put all @@sseeee tags together.

       Tags come in two types:


       +o Standalone tags - Can be placed only in the tag section that  follows

       the desription. There tags are not set off with curly braces: @tag.


       +o  Inline  tags - Can be placed anywhere in the comments description or

       in the comments for standalone tags. Inline tags are set off with curly
       braces:{@@ttaagg}.

       For  information  about tags we might introduce in future releases, see
       Proposed Tags.

       The current tags are:




                            +-------+-------+

                            |     TTaagg      | IInnttrroodduucceedd  |
                            |              | in JDK      |

                            +-------+-------+

                            |@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         |

                            +-------+-------+

       For custom tags, see the -tag option.



       @@aauutthhoorr name-text

              Adds an "Author" entry with the specified name-text to the  gen-

              erated  docs when the -aauutthhoorr option is used.  A doc comment may

              contain multiple @@aauutthhoorr tags.  You can  specify  one  name  per
              @@aauutthhoorr  tag or multiple names per tag.  In the former case, the
              JJaavvaaddoocc tool inserts a comma (,,) and space  between  names.   In

              the  latter case, the entire text is simply copied to the gener-

              ated document without being  parsed.   Therefore,  use  multiple
              names per line if you want a localized name separator other than
              a comma.


       @@ddeepprreeccaatteedd deprecated-text

              Adds a comment indicating that this API should no longer be used

              (even though it might continue to work).  jjaavvaaddoocc moves the dep-

              recated-text ahead of the description, placing it in italics and

              preceding it with a bold warning: "DDeepprreeccaatteedd".


              The  first  sentence of deprecated-text should at least tell the

              user when the API was deprecated and what to use as  a  replace-

              ment.   jjaavvaaddoocc  copies  just  the first sentence to the summary
              section and index.  Subsequent sentences can also explain why it
              has  been  deprecated.   You  should  include a {@@lliinnkk} tag (for
              jjaavvaaddoocc 1.2 or later) that points to the replacement API:



              +o For jjaavvaaddoocc 1.2, use a {@@lliinnkk} tag. This creates the link  in-

                line, where you want it. For example:

                     //****
                      ** @@ddeepprreeccaatteedd  AAss ooff JJDDKK 11..11,, rreeppllaacceedd bbyy

                      **    {{@@lliinnkk ##sseettBBoouunnddss((iinntt,,iinntt,,iinntt,,iinntt))}}

                      **//


              +o For  jjaavvaaddoocc  1.1, the standard format is to create a @@sseeee tag

                (which cannot be in-line) for each @@ddeepprreeccaatteedd tag.


              For more about deprecation, see the @@ddeepprreeccaatteedd tag.

       {{@@ccooddee tteexxtt}}
              Equivalent to {@literal} .

       Displays text in code font without interpreting the text as HTML markup

       or  nested javadoc tags. This enables you to use regular angle brackets

       ( < and > ) instead of the HTML entities ( < and > ) in doc  com-

       ments, such as in parameter types (  ), inequalities ( 3 < 4 ),

       or arrows ( <- ). For example, the doc comment text:


            {@code AC}

       displays in the generated HTML page unchanged as:

            AC

       The noteworthy point is that the  is not interpreted as  boldand  is
       in code font.


       If  you  want  the same functionality without the code font, use {@lit-

       eral}.

       {{@@ddooccRRoooott}}

              Represents the relative path to the generated document's (desti-

              nation)  root  directory  from any generated page.  It is useful
              when you want to include a file, such as  a  copyright  page  or
              company  logo,  that  you  want  to reference from all generated
              pages.  Linking to the copyright page from the  bottom  of  each
              page is common.

              This  {{@@ddooccRRoooott}} tag can be used both on the command line and in
              a doc comment:

              1.  On the command  line,  where  the  header/footer/bottom  are
                  defined:


                  jjaavvaaddoocc  -bboottttoomm  ''<>CCooppyy-

                  rriigghhtt<>''


              NOTE - When using {@@ddooccRRoooott} this way in a make file, some make-

              file  programs require special escaping for the brace {} charac-

              ters. For example, the Inprise MAKE version 5.2 running on  Win-

              dows requires double braces: {{@@ddooccRRoooott}}. It also requires dou-

              ble (rather than single) quotes to enclose arguments to  options

              such  as -bottom (with the quotes around the href argument omit-

              ted).

              2.     In a doc comment:

                     //****
                     ** SSeeee tthhee <>CCooppyyrriigghhtt<>..
                     **//

              The reason this tag is needed is because the generated docs  are

              in  hierarchical  directories, as deep as the number of subpack-

              ages.  This expression:

                   <>

              would resolve to:

                   <>         ...       for
              java/lang/Object.java

              and

                   <>       ...      for
              java/lang/ref/Reference.java


       @@eexxcceeppttiioonn class-name description

              The @@eexxcceeppttiioonn tag is a synonym for @@tthhrroowwss.

       {@@iinnhheerriittDDoocc}

              Inherits documentation from the nearest superclass into the cur-

              rent  doc  comment. This allows comments to be abstracted up the
              inheritance tree, and enables developers  to  write  around  the
              copied text. Also see inheriting comments.

       This tag can be placed in two positions:

       +o      In  the comment body (before the first standalone tag), where it
              will copy the entire comment body from its superclass.

       +o      In the text argument of a standalone tag, where it will copy the
              text of the tag from its superclass.


       {@@lliinnkk " package.class#member label" }

              Inserts  an  in-line link with visible text llaabbeell that points to

              the documentation for the specified  package,  class  or  member
              name of a referenced class.


              This  tag is very similar to @@sseeee - both require the same refer-

              ences and accept exactly the same syntax for  package.class#mem-

              ber and llaabbeell..  The main difference is that {@@lliinnkk} generates an

              in-line link rather than placing the link in the "See Also" sec-

              tion. Also, the {@@lliinnkk} tag begins and ends with curly braces to

              separate it from the rest of the in-line text. If  you  need  to

              use "}" inside the label, use the HTML entity notation &&##112255;;


              There  is  no  limit  to the number of {@@lliinnkk} tags allowed in a
              sentence.  You can use this tag in the  description  part  of  a
              documentation comment or in the text portion of any tag (such as
              @@ddeepprreeccaatteedd, @@rreettuurrnn, or @@ppaarraamm).


              For example, here is a comment that refers to  the  ggeettCCoommppoonneenn-

              ttAAtt((iinntt,, iinntt)) method:


              UUssee tthhee {{@@lliinnkk ##ggeettCCoommppoonneennttAAtt((iinntt,, iinntt)) ggeettCCoommppoonneennttAAtt} method.


              >From  this,  the  standard  doclet would generate the following
              HTML (assuming it refers to another class in the same package):

              UUssee tthhee

              <>\\

                             ggeettCCoommppoonneennttAAtt<>mmeetthhoodd..

              which appears on the web page as:

              UUssee tthhee ggeettCCoommppoonneennttAAtt mmeetthhoodd..

              You can extend {@@lliinnkk} to link to classes not  being  documented

              by using the -lliinnkk otion.



       {@@lliinnkkppllaaiinn " package.class#member label"}

              Indentical  to  {@@lliinnkk}, except the link's label is displayed in
              plain text than code font. Useful when the label is plain  text.
              Example:

       RReeffeerr ttoo {{@@lliinnkkppllaaiinn add() the overridden method}.

       This would display as

       RReeffeerr ttoo tthhee oovveerrrriiddddeenn mmeetthhoodd..


       {{@@lliitteerraall text}
              Displays  text  without  interpreting the text as HTML markup or

              nested javadoc tags. This  enables  you  to  use  regular  angle

              brackets  (  <  and  > ) instead of the HTML entities ( < and
              > ) in doc comments, such as in parameter types (  ),

              inequalities  ( 3 < 4 ), or arrows ( <- ).  For example, the doc

              comment text:

            {@literal AC}

       displays unchanged in the generated HTML page in your browser, as:

            AC

       The noteworthy point is that the  is not interpreted as bold(and  it
       is not in code font).

       If  you want the same functionality but with the text in code font, use
       {@code} .


       @@ppaarraamm parameter-name description

              Adds a parameter with the specified parameter-name  followed  by

              the  specified  description  to  the "Parameters" section.  When
              writing the doc comment, you may continue the  description  onto
              multiple  lines.   This tag is valid only in a doc comment for a
              method, constructor or class.


       The parameter-name can be the name of a parameter in a method  or  con-

       structor,  or the name of a type parameter of a class. Use angle brack-

       ets around this parametername to specify the use of a  type  parameter,
       such as:

            ,nf  /**  *  @param  Type of element stored in a list */ public
            interface List extends Collection { }

       For more details, see writing @param tags.

       @@rreettuurrnn description
              Adds a "Returns" section with the description text.   This  text
              should describe the return type and permissible range of values.


       @@sseeee label

              Adds a link as defined by URL#value. The URL#value is a relative

              or  absolute URL. The Javadoc tool distinguishes this from other

              cases by looking for a less-than symbol (<) as the first charac-

              ter.  For example:


            @see Java Spec


       This generated a link such as:

            See Also: "Java Spec"

       @@sseeee string
              Adds  a text entry for string. No link is generated.  The string
              is a book or other reference to  information  not  available  by
              URL. The JJaavvaaddoocc tool distinguishes this from the previous cases

              by looking for a double-quote (") as the first  character.   For

              example:

                   @see "The Java Programming Language"
              This generates text such as:

                   SSeeee AAllssoo::
                        "The Java Programming Language"

       @@sseeee <>label<>

              Adds  a  link as defined by URL#value.  The URL#value is a rela-

              tive or absolute URL. The JJaavvaaddoocc tool distinguishes  this  from

              other  cases  by looking for a less-than symbol (<<) as the first

              character.  For example:


                   @@sseeee <>JJaavvaa SSppeecc<>


              This generates a link such as:

                  SSeeee AAllssoo::
                        JJaavvaa SSppeecc


       @@sseeee package.class#member label

              Adds a link, with visible text label, that points to  the  docu-

              mentation  for  the  specified name in the Java Language that is
              referenced.  The label is optional; if omitted, the name appears
              instead  as the visible text, suitably shortened (see How a Name
              Is Displayed).  Use the label when you want the visible text  to
              be abbreviated or different from the name.


              In  version 1.2, just the name but not the label would automati-

              cally appear in <> HTML  tags.   Starting  with  1.2.2,  the
              <>  is  always  included around the visible text, whether or
              not a label is used.


              +o package.class#member is any valid name in  the  Java  Language

                that  is  referenced  (package, class, interface, constructor,
                method, or field name), except that you replace the dot  ahead

                of the member name with a hash character (#).  If this name is

                in the documented classes, the JJaavvaaddoocc tool will automatically
                create  a  link to it.  To create links to external referenced

                classes, use the -lliinnkk option.  Use either of  the  other  two

                @@sseeee  forms for referring to documentation of a name that does
                not belong to a referenced class.  This argument is  described
                at greater length below under Specifying a Name.

              +o label  is  optional  text that is visible as the link's label.
                The label can contain white space.  If  a  label  is  omitted,

                then package.class.member will appear, suitably shortened rel-

                ative to the current class and package (see How a Name Is Dis-

                played).


              +o A  space  is  the  delimiter  between package.class#member and

                label.  A space inside parentheses does not indicate the start
                of  a  label,  so  spaces  can be used between parameters in a
                method.


              Example - In this example, an @@sseeee tag (in the Character  class)

              refers  to  the  equals  method  in  the  String class.  The tag
              includes    both    arguments,     that     is,     the     name

              "SSttrriinngg##eeqquuaallss((OObbjjeecctt))" and the label "eeqquuaallss":


                    //****

                    ** @@sseeee SSttrriinngg##eeqquuaallss((OObbjjeecctt)) eeqquuaallss

                    **//

              The standard doclet produces HTML something like this:

                  <>
                  <><>SSeeee AAllssoo::<>

                  <><                               ((jjaavvaa..llaanngg..OObbjjeecctt))"">><>eeqquuaallss<><>
                  <>

              The  above  looks  something  like  this in a browser, where the
              label is the visible link text:

                   SSeeee AAllssoo::
                        eeqquuaallss


              SSppeecciiffyyiinngg aa NNaammee - This package.class#member name can be either

              fully qualified, such as jjaavvaa..llaanngg..SSttrriinngg##ttooUUppppeerrCCaassee(()), or not,

              such as SSttrriinngg##ttooUUppppeerrCCaassee(()) or ##ttooUUppppeerrCCaassee(()).   If  less  than

              fully-qualified,  the JJaavvaaddoocc tool uses the normal Java compiler

              search order to find it, further described below in Search order
              for  @@sseeee.   The name can contain whitespace within parentheses,
              such as between method arguments.


              Of course the advantage to providing shorter,  "partially-quali-

              fied"  names  is  that they are less to type and less clutter in
              the source code.  The following table shows the different  forms
              of  the  name, where Class can be a class or interface, Type can
              be a class, interface, array, or primitive, and method can be  a
              method or constructor.



              +------------------------------+

              |       TTyyppiiccaall ffoorrmmss ffoorr @@sseeee package.class#member         |

              +------------------------------+

              |Referencing a member of the current class                  |

              |@see  #field                                               |

              |@see  #method(Type, Type,...)                              |

              |@see  #method(Type argname, Type argname,...)              |

              |Referencing another class in the current or imported       |
              |packages                                                   |

              |@see  Class#field                                          |

              |@see  Class#method(Type, Type,...)                         |

              |@see  Class#method(Type argname, Type argname,...)         |

              |@see  Class                                                |
              |Referencing another package (fully qualified)              |

              |@see  package.Class#field                                  |

              |@see  package.Class#method(Type, Type,...)                 |

              |@see  package.Class#method(Type argname, Type argname,...) |

              |@see  package.Class                                        |
              |@see  package                                              |

              +------------------------------+

              The following notes apply to the above table:


              +o The  first  set of forms (with no class or package) will cause
                the JJaavvaaddoocc tool to search only through  the  current  class's
                hierarchy.   It  will  find  a  member of the current class or
                interface, one of its superclasses or superinterfaces, or  one

                of its enclosing classes or interfaces (search steps 1-3).  It

                will not search the rest of the current package or other pack-

                ages (search steps 4-5).


              +o If  any  method  or  constructor  is entered as a name with no
                parentheses, such as getValue, and if no field with  the  same
                name  exists, the JJaavvaaddoocc tool will correctly create a link to
                it, but will print a warning message reminding you to add  the
                parentheses  and arguments.  If this method is overloaded, the

                JJaavvaaddoocc tool links to the first method that its search encoun-

                ters, which is unspecified.

              +o Nested  classes  must  be  specified  as oouutteerr..iinnnneerr, not only
                iinnnneerr, for all forms.


              +o As stated, the hash character (##), rather than a dot (..), sep-

                arates a member from its class.  This enables the JJaavvaaddoocc tool
                to resolve ambiguities, since the dot also separates  classes,
                nested  classes,  packages,  and  subpackages.   However,  the
                JJaavvaaddoocc tool is generally lenient and will  properly  parse  a
                dot  if you know there is no ambiguity, though it will print a
                warning.

              SSeeaarrcchh OOrrddeerr ffoorr @@sseeee:: The JJaavvaaddoocc tool will process an @@sseeee tag

              that  appears  in  a  source  file  (..jjaavvaa), package file (ppaacckk-

              aaggee..hhttmmll), or overview file (oovveerrvviieeww..hhttmmll).  In the latter  two
              files, you must fully qualify the name you supply with @@sseeee.  In
              a source file, you can specify a name that is fully qualified or
              partially qualified.

              When  the  JJaavvaaddoocc  tool  encounters an @@sseeee tag in a ..jjaavvaa file
              that is not fully qualified, it searches for the specified  name
              in the same order as the Java compiler would (except the JJaavvaaddoocc
              tool will not detect certain  namespace  ambiguities,  since  it
              assumes  the  source code is free of these errors).  This search

              order is formally defined in Chapter 6, "Names" of the Java Lan-

              guage  Specification,  Second Edition. The JJaavvaaddoocc tool searches

              for that name through all related and imported classes and pack-

              ages.  In particular, it searches in this order:


              1.  The current class or interface
              2.  Any  enclosing  classes  and  interfaces,  searching closest
                  first
              3.  Any  superclasses  and  superinterfaces,  searching  closest
                  first
              4.  The current package
              5.  Any  imported packages, classes and interfaces, searching in
                  the order of the import statement

              The JJaavvaaddoocc tool continues to search recursively  through  steps

              1-3  for  each class it encounters until it finds a match.  That

              is, after it searches through the current class and its  enclos-

              ing  class  E,  it  searches through E's superclasses before E's
              enclosing classes.  In steps 4 and 5, the JJaavvaaddoocc tool does  not
              search  classes  or interfaces within a package in any specified
              order (that order depends on the particular compiler).  In  step

              5,  the JJaavvaaddoocc tool will look in jjaavvaa..llaanngg,ssiinncceethatiissautomati-

              cally imported by all programs.

              The JJaavvaaddoocc tool won't necessarily look in subclasses, nor  will
              it  look  in other packages even if their documentation is being
              generated in the same run.  For example, if the @@sseeee tag  is  in
              jjaavvaa..aawwtt..eevveenntt..KKeeyyEEvveenntt  class  and  refers  to  a  name  in the
              jjaavvaa..aawwtt package, jjaavvaaddoocc will not look in that  package  unless
              that class imports it.


              HHooww  aa  NNaammee  iiss  DDiissppllaayyeedd  -  If  label is omitted, then pack-

              age.class.member will appear.  In general, it will  be  suitably

              shortened relative to the current class and package.  By "short-

              ened", we mean the JJaavvaaddoocc tool will display  only  the  minimum
              name necessary.  For example, if the String.toUpperCase() method

              contains references to a member of the same class and to a  mem-

              ber  of a different class, the class name will be displayed only
              in the latter case:


              TTyyppee       EExxaammppllee                       DDiissppllaayyss AAss
              ooff

              RReeff-

              eerreennccee








              @see tag   @@sseeee                          toLowerCase()

              refers     SSttrriinngg##ttooLLoowweerrCCaassee(())          (omits the class name)

              to
              member
              of
              the
              same
              class

              @see       @@sseeee                          Character.toLowerCase(char)

              tag        CChhaarraacctteerr##ttooLLoowweerrCCaassee((cchhaarr))   (includes the class name)

              refers
              to
              member
              of a

              differ-

              ent
              class

              EExxaammpplleess ooff @@sseeee:: The comment to the right shows  how  the  name
              would  be  displayed  if  the  @@sseeee tag is in a class in another
              package, such as jjaavvaa..aapppplleett..AApppplleett:



              Example                                  See also:

              @@sseeee jjaavvaa..llaanngg..SSttrriinngg                    // String
              @see java.lang.String The String class   / h Srn cas              @@sseeee SSttrriinngg                              // String

              @@sseeee SSttrriinngg##eeqquuaallss((OObbjjeecctt))               // String.equals(Object)

              @@sseeee SSttrriinngg##eeqquuaallss                       // String.equals\

                                                             (java.lang.Object)

              @@sseeee jjaavvaa..llaanngg..OObbjjeecctt##wwaaiitt((lloonngg))         // java.lang.Object.\

                                                             wait(long)

              @@sseeee CChhaarraacctteerr##MMAAXXRRAADDIIXX                 // Character.MAXRADIX

              @@sseeee <>JJaavvaa SSppeecc<>   // Java Spec
              @see "The Java Programming Language"     / Te aa rgamn \                                                             Language"

       You can extend @see to link to classes not being documented

              by using the -lliinnkk option.



       @@ssiinnccee since-text

              Adds a "Since" heading with the specified since-text to the gen-

              erated  documentation.   The text has no special internal struc-

              ture.  This tag means that this change or  feature  has  existed

              since  the  software  release  specified by the since-text.  For

              example:

              @@ssiinnccee 11..44

       For source code in the Java platform, this tag indicated the version of
       the  Java platform API specification (not necessarily when it was added
       to the reference implementation).


       @@sseerriiaall field-description||include||exclude

              Used in the doc comment for a default serializable field.


              An optional field-description augments the doc comment  for  the

              field.  The combined description must explain the meaning of the

              field and list the acceptable values.  If needed,  the  descrip-

              tion  can  span  multiple  lines.  The standard doclet adds this
              information to the serialized form page.

              The iinncclluuddee and eexxcclluuddee arguments identify whether  a  class  or
              package  should be included or excluded from the serialized form
              page. They work as follows:


              +o A public or protected class that implements
                SSeerriiaalliizzaabbllee is iinncclluuddeedd unless the class (or its package)  is
                marked @@sseerriiaall eexxcclluuddee.


              +o A private or package-private class that implements

                SSeerriiaalliizzaabbllee is eexxcclluuddeedd unless that class (or its package) is
                marked @@sseerriiaall iinncclluuddee.

              Examples: The jjaavvaaxx..sswwiinngg package is marked @@sseerriiaall eexxcclluuddee  (in
              package.html).  The  public class jjaavvaa..sseerrccuurriittyy..BBaassiiccPPeerrmmiissssiioonn

              is  marked   @@sseerriiaall   eexxcclluuddee..    The   package-private   class

              jjaavvaa..uuttiill..PPrrooppeerrttyyPPeerrmmiissssiioonnCCoolllleeccttiioonn    is    marked   @@sseerriiaall
              iinncclluuddee..

              The tag @@sseerriiaall at a class level overrides @@sseerriiaall at a  package
              level.

              For  more information about how to use these tags, along with an
              example, see "Documenting Serializable Fields  and  Data  for  a

              Class,"  Section 1.6 of the Java Object Serialization Specifica-

              tion.  Also see the "Serialization FAQ," which covers the  ques-

              tions,  "Why do I see jjaavvaaddoocc warnings stating that I am missing
              @@sseerriiaall tags? for private fields if I  am  not  running  jjaavvaaddoocc

              with the -pprriivvaattee switch?"




       @@sseerriiaallFFiieelldd field-name  field-type  field-description

              Documents  an  ObjectStreamField  component  of  a  Serializable
              class's serialPersistentFields  member.   One  @@sseerriiaallFFiieelldd  tag
              should be used for each ObjectStreamField component.


       @@sseerriiaallDDaattaa data-description

              The  data-description  documents  the types and order of data in

              the serialized  form.   Specifically,  this  data  includes  the
              optional  data  written  by  the writeObject method and all data

              (including base classes) written by the  Externalizable.writeEx-

              ternal method.

              The  @@sseerriiaallDDaattaa  tag  can  be  used  in the doc comment for the

              writeObject, readObject, writeExternal, and  readExternal  meth-

              ods.


       @@tthhrroowwss class-name  description

              The  @@tthhrroowwss  and @@eexxcceeppttiioonn tags are synonyms.  Adds a "Throws"

              subheading to the generated documentation, with  the  class-name

              and  description text.  The class-name is the name of the excep-

              tion that may be thrown by the method.  If  this  class  is  not
              fully  specified, the JJaavvaaddoocc tool uses the search order to look
              up this class.  Multiple @throws tags can beused in a given  doc
              comment for the same or different exceptions.

       To  ensure that all checked exceptions are documented, if a @throws tag
       does not exist for an exception inthe throws clause, the  Javadoc  tool

       automatically  adds that exception to the HTML output (with no descrip-

       tion) as if it were documented with @throws tag.


       The @throws documentation is copied from an overridden method to a sub-

       class  only when the exception is explicitly declared in the overridden
       method. The same is true for copying  from  an  interfacemethod  to  an
       implementing  method.   You  can  use  {@inheritDoc} to force@throws to
       inherit documentation.

       For more details, see Writing @throws tags.


       {{@@vvaalluuee ppaacckkaaggee..ccllaassss##ffiieelldd}}

              When {@value} is used (without any argument) in the doc  command
              of a static field, it displays the value of that constant:

            /**
            * The value of this constant is {@value}.
            */
            public static final String SCRIPTSTART = "