neulab/tldr huggingface dataset:
The full documentation is maintained as a PDF manual.  The command
texdoc texdoc
WHIPTAIL(1)                  General Commands Manual                 WHIPTAIL(1)
whiptail - display dialog boxes from shell scripts
whiptail [ --title title ] [ --backtitle backtitle ] [ --clear ] [ --default-item string ] [ --defaultno ] [ --fb ] [ --nocancel ] [ --yes-button text ] [ --no-button text ] [ --ok-button text ] [ --cancel-button text ] [ --noitem [ ] --output-fd fd ] [ --separate-output ] [ --scrolltext ] [ --topleft ] box-options
whiptail is a program that will let you present a variety of questions or display messages using dialog boxes from a shell script. Currently, these types of dialog boxes are implemented:
yes/no box, menu box, input box, message box, text box, info box, checklist box, radiolist box gauge box, and password box.
--clear The screen will be cleared to the screen attribute on exit.  This doesn't work in an xterm (and descendants) if alternate screen switching is enabled, because in that case slang writes to (and clears) an alternate screen.
--defaultno The dialog box will open with the cursor over the No button.
--default-item string Set  the default item in a menu box.  Normally the first item in the box is the default.
--fb, --fullbuttons Use full buttons. (By default, whiptail uses compact buttons).
--nocancel The dialog box won't have a Cancel button.
--yes-button text Set the text of the Yes button.
--no-button text Set the text of the No button.
--ok-button text Set the text of the Ok button.
--cancel-button text Set the text of the Cancel button.
--noitem The menu, checklist and radiolist widgets will display tags only, not the item strings. The menu widget still needs some items specified, but checklist and radiolist expect only tag and status.
--notags Don't display tags in the menu, checklist and radiolist widgets.
--separate-output For checklist widgets, output result one line at a time, with no quoting.  This facilitates parsing by another program.
--output-fd fd Direct output to the given file descriptor.  Most whiptail scripts write to standard error, but  error  messages  may  also  be written there, depending on your script.
--title title Specifies a title string to be displayed at the top of the dialog box.
--backtitle backtitle Specifies a backtitle string to be displayed on the backdrop, at the top of the screen.
--scrolltext Force the display of a vertical scrollbar.
--topleft Put window in top-left corner.
-h, --help Print a help message and exit.
Box Options
--yesno text height width A yes/no dialog box of size height rows by width columns will be displayed. The string specified by text is displayed inside the dialog box. If this string is too long to be fit in one line, it will be automatically divided into multiple lines at appropriate places. The text string may also contain the sub-string "\n" or newline characters `\n' to control line breaking explicitly.  This dialog box is useful for asking questions that require the user to answer either yes or no.  The dialog box has a Yes button and a No button, in which the user can switch between by pressing the TAB key.
--msgbox text height width A message box is very similar to a yes/no box.  The only difference between a message box and a yes/no box is that a message box has only a single OK button. You can use this dialog box to display any message you like.  After reading the message, the user can press the ENTER key so that whiptail will exit and the calling shell script can continue its operation.
--infobox text height width An info box is basically a message box.  However, in this case, whiptail will exit immediately after displaying the message to the user. The screen is not cleared when whiptail exits, so that the message will remain on the screen until the calling shell script clears it later. This is useful when you want to inform the user that some operations are carrying on that may require some time to finish.
--inputbox text height width [init] An input box is useful when you want to ask questions that require the user to input a string as the answer. If init is supplied it is used to initialize the input string.  When inputing the string, the BACKSPACE key can be used to correct typing errors. If the input string is longer than the width of the dialog box, the input field will be scrolled. On exit, the input string will be printed on stderr.
--passwordbox text height width [init] A password box is similar to an input box, except the text the user enters is not displayed. This is useful when prompting for passwords or other sensitive information. Be aware that if anything is passed in "init", it will be visible in the system's process table to casual snoopers. Also, it is very confusing to the user to provide them with a default password they cannot see. For these reasons, using "init" is highly discouraged.
--textbox file height width A text box lets you display the contents of a text file in a dialog box. It is like a simple text file viewer. The user can move through the file by using the UP/DOWN, PGUP/PGDN and HOME/END keys available on most keyboards.  If the lines are too long to be displayed in the box, the LEFT/RIGHT keys can be used to scroll the text region horizontally. For more convenience, forward and backward searching functions are also provided.
--menu text height width menu-height [ tag item ] ... As its name suggests, a menu box is a dialog box that can be used to present a list of choices in the form of a menu for the user to choose. Each menu entry consists of a tag string and an item string. The tag gives the entry a name to distinguish it from the other entries in the menu. The item is a short description of the option that the entry represents. The user can move between the menu entries by pressing the UP/DOWN keys, the first letter of the tag as a hot-key. There are menu-height entries displayed in the menu at one time, but the menu will be scrolled if there are more entries than that. When whiptail exits, the tag of the chosen menu entry will be printed on stderr.
--checklist text height width list-height [ tag item status ] ... A checklist box is similar to a menu box in that there are multiple entries presented in the form of a menu.  You can select and deselect items using the SPACE key.  The initial on/off state of each entry is specified by status.  On exit, a list of the tag strings of those entries that are turned on will be printed on stderr.
--radiolist text height width list-height  [ tag item status ] ... A radiolist box is similar to a menu box.  The only difference is that you can indicate which entry is currently selected, by setting its status to on.
--gauge text height width percent A gauge box displays a meter along the bottom of the box.  The meter indicates a percentage.  New percentages are read from standard input, one integer per line.  The meter is updated to reflect each new percentage.  If stdin is XXX, the first following line is a percentage and subsequent lines up to another XXX are used for a new prompt.  The gauge exits when EOF is reached on stdin.
whiptail interprets arguments starting with a dash "-" as being arguments.  To avoid this, and start some text in, for example, a menubox item, with a dash, whiptail honours the getopt convention of accepting the special argument "--" which means that all following arguments with dashes are to be treated verbatim and not parsed as options.
Exit status is 0 if whiptail is exited by pressing the Yes or OK button, and 1 if the No or Cancel button is pressed. Otherwise, if errors occur inside whiptail or whiptail is exited by pressing the ESC key, the exit status is -1.
Based on the man page for dialog(1) by:
Savio Lam (lam836@cs.cuhk.hk) - version 0.3
Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version 0.4
Modifications for whiptail by:
Enrique Zanardi (ezanard@debian.org)
Alastair McKinstry (mckinstry@debian.org)
javadoc(1)                   General Commands Manual                  javadoc(1)
Name javadoc - The Java API Documentation Generator
Generates HTML pages of API documentation from Java source files. This document contains Javadoc examples for Solaris.
javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]
Arguments can be in any order. See processing of Source Files for details on how the Javadoc tool determines which ".java" files to process.
options Command-line options, as specified in this document. To see a typical use of javadoc options, see Real-World Example.
packagenames A series of names of packages, separated by spaces, such as java.lang java.lang.reflect java.awt. You must separately specify each package you want to document. Wildcards are not allowed; use -subpackages for recursion. The Javadoc tool uses -sourcepath to look for these package names. See Example - Documenting One or More Packages
sourcefilenames A series of source file names, separated by spaces, each of which can begin with a path and contain a wildcard such as asterisk (*). The Javadoc 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 the Java Language Specification). 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 template files The path that precedes the source file name determines where javadoc will look for the file. (The Javadoc tool does not use -sourcepath to look for these source file names.) Relative paths are relative to the current directory, so passing in Button.java is identical to ./Button.java. A source file name with an absolute path and a wildcard, for example, is /home/src/java/awt/Graphics*.java. See Example - Documenting One or More Classes. You can also mix packagenames and sourcefilenames, as in Example - Documenting Both Packages and Classes
-subpackages pkg1:pkg2:... Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying packagenames or sourcefilenames.
@argfiles One or more files that contain a list of Javadoc options, packagenames and sourcefilenames in any order. Wildcards (*) and -J options are not allowed in these files.
The Javadoc 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 use it to generate the API (Application Programming Interface) documentation or the implementation documentation for a set of source files.
You can run the Javadoc tool on entire packages, individual source files, or both. When documenting entire packages, you can either use -subpackages for traversing recursively down from a top-level directory, or pass in an explicit list of package names. When documenting individual source files, you pass in a list of source (.java) filenames. Examples are given at the end of this document. How Javadoc processes source files is covered next.
Processing of source files The Javadoc tool processes files that end in ".java" plus other files described under Source Files. If you run the Javadoc tool by explicitly passing in individual source filenames, you can determine exactly which ".java" files are processed. However, that is not how most developers want to work, as it is simpler to pass in package names. The Javadoc tool can be run three ways without explicitly specifying the source filenames. You can (1) pass in package names, (2) use -subpackages, and (3) use wildcards with source filenames (*.java). In these cases, the Javadoc tool processes a ".java" file only if it fulfills all of the following requirements:
o Its name, after stripping off the ".java" suffix, is actually a legal class name (see the Java Language Specification for legal characters)
o Its directory path relative to the root of the source tree is actually a legal package name (after converting its separators to dots)
o Its package statement contains the legal package name (specified in the previous bullet)
Processing of links - 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 -link and -linkoffline options.
Other processing details - The Javadoc tool produces one complete document each time it is run; it cannot do incremental builds -- that is, it cannot modify or directly incorporate results from previous runs of the Javadoc tool. However, it can link to results from other runs, as just mentioned.
As implemented, the Javadoc tool requires and relies on the java compiler to do its job. The Javadoc tool calls part of javac 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 Javadoc tool also picks up user-supplied documentation from documentation comments in the source code.
In fact, the Javadoc tool will run on .java source files that are pure stub files with no method bodies. This means you can write documentation comments and run the Javadoc 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 Javadoc tool documents default constructors (see Java Language Specification) that are present in the .class files but not in the source code.
In many cases, the Javadoc tool allows you to generate documentation for source files whose code is incomplete or erroneous. This is a benefit that enables you to generate documentation before all debugging and troubleshooting is done. For example, according to the Java Language Specification, a class that contains an abstract method should itself be declared abstract. The Javadoc tool does not check for this, and would proceed without a warning, whereas the javac compiler stops on this error. The Javadoc tool does do some primitive checking of doc comments. Use the DocCheck doclet to check the doc comments more thoroughly.
When the Javadoc tool builds its internal structure for the documentation, it loads all referenced classes. Because of this, the Javadoc 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 @ http://docs.oracle.com/javase/7/docs/technotes/tools/findingclasses.html. Generally speaking, classes you create must either be loaded as an extension or in the Javadoc tool's class path.
Javadoc Doclets You can customize the content and format of the Javadoc tool's output by using doclets. The Javadoc tool has a default "built-in" doclet, called the standard doclet, that generates HTML-formatted API documentation. 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 following locations:
o Javadoc Doclets @ http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html
o The -doclet command-line option
When a custom doclet is not specified with the -doclet command line option, the Javadoc tool will use the default standard doclet. The javadoc 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.
Related Documentation and Doclets o Javadoc Enhancements @ http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html for details about improvements added in Javadoc.
o Javadoc FAQ @ http://java.sun.com/j2se/javadoc/faq/index.html for answers to common questions, information about Javadoc-related tools, and workarounds for bugs.
o How to Write Doc Comments for Javadoc @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html for more information about Sun conventions for writing documentation comments.
o Requirements for Writing API Specifications @ http://java.sun.com/j2se/javadoc/writingapispecs/index.html - Standard requirements used when writing the Java SE Platform Specification. It can be useful whether you are writing API specifications in source file documentation comments or in other formats. It covers requirements for packages, classes, interfaces, fields and methods to satisfy testable assertions.
o Documentation Comment Specification @ http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html - 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 edition.)
o DocCheck Doclet @ http://www.oracle.com/technetwork/java/javase/documentation/index-141437.html - Checks doc comments in source files and generates a report listing the errors and irregularities it finds. It is part of the Doc Check Utilities.
o MIF Doclet @ http://java.sun.com/j2se/javadoc/mifdoclet/ - Can automate the generation of API documentation in MIF, FrameMaker and PDF formats. MIF is Adobe FrameMaker's interchange format.
Terminology The terms documentation comment, doc comment, main description, tag, block tag, and in-line tag are described at Documentation Comments. These other terms have specific meanings within the context of the Javadoc tool:
generated document The document generated by the javadoc 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 of a program element written in the Java Language -- that is, the name of a package, class, interface, field, constructor or method. A name can be fully-qualified, such as java.lang.String.equals(java.lang.Object), or partially-qualified, such as equals(Object).
documented classes The classes and interfaces for which detailed documentation is generated during a javadoc run. To be documented, the source files must be available, their source filenames or package names must be passed into the javadoc command, and they must not be filtered out by their access modifier (public, protected, package-private or private). We also refer to these as the classes included in the javadoc output, or the included classes.
included classes Classes and interfaces whose details are documented during a run of the Javadoc tool. Same as documented classes.
excluded classes Classes and interfaces whose details are not documented during a run of the Javadoc tool.
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 references 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 definition has changed since 1.3 @ http://docs.oracle.com/javase/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses.) When the Javadoc 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 Javadoc tool can derive enough information from the .class files to determine their existence and the fully-qualified names of their members.
external referenced classes The referenced classes whose documentation is not being generated during a javadoc run. In other words, these classes are not passed into the Javadoc tool on the command line. Links in the generated documentation to those classes are said to be external references or external links. For example, if you run the Javadoc tool on only the java.awt package, then any class in java.lang, such as Object, is an external referenced class. External referenced classes can be linked to using the -link and -linkoffline options. An important property of an external referenced class is that its source comments are normally not available to the Javadoc run. In this case, these comments cannot be inherited.
The Javadoc tool will generate output originating from four different types of "source" files: Java language source files for classes (.java), package comment files, overview comment files, and miscellaneous unprocessed files. This section also covers test files and template files that can also be in the source tree, but which you want to be sure not to document.
Class Source Code Files Each class or interface and its members can have their own documentation comments, contained in a .java file. For more details about these doc comments, see Documentation Comments.
Package Comment Files Each package can have its own documentation comment, contained in its own "source" file, that the Javadoc 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 have a choice of two files to place your comments:
o package-info.java - Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is generally preferred over package.html.
o package.html - Can contain only package comments and Javadoc tags, no package annotations.
A package may have a single package.html file or a single package-info.java file but not both. Place either file in the package directory in the source tree along with your .java files.
package-info.java - This file can contain a package comment of the following structure -- the comment is placed before the package declaration:
File: java/applet/package-info.java /** * Provides the classes necessary to create an * applet and the classes an applet uses * to communicate with its applet context. * <p> * The applet framework involves two entities: * the applet and the applet context. * An applet is an embeddable window (see the * {@link java.awt.Panel} class) with a few extra * methods that the applet context can use to * initialize, start, and stop the applet. * * @since 1.0 * @see java.awt */ package java.lang.applet;
Note that while the comment separators /** and /* must be present, the leading asterisks on the intermediate lines can be omitted.
package.html - This file can contain a package comment of the following structure -- the comment is placed in the <body> element:
File: java/applet/package.html <HTML> <BODY> Provides the classes necessary to create an applet and the classes an applet uses to communicate with its applet context. <p> The applet framework involves two entities: the applet and the applet context. An applet is an embeddable window (see the {@link java.awt.Panel} class) with a few extra methods that the applet context can use to initialize, start, and stop the applet.
@since 1.0 @see java.awt </BODY> </HTML>
Notice this is just a normal HTML file and does not include a package declaration. The content of the package comment file is 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 <body> and the first sentence. You can include package tags; as with any documentation comment, all block tags must appear after the main description. If you add a @see tag in a package comment file, it must have a fully-qualified name. For more details, see the example of package.html @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#packagecomments.
Processing of package comment file - When the Javadoc tool runs, it will automatically look for the package comment file; if found, the Javadoc tool does the following:
o Copies the comment for processing. (For package.html, copies all content between <body> and </body> HTML tags. You can include a <head> section to put a <title>, source file copyright statement, or other information, but none of these will appear in the generated documentation.)
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 @ http://docs.oracle.com/javase/7/docs/api/java/applet/package-summary.html.
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 @ http://docs.oracle.com/javase/7/docs/api/overview-summary.html. The end-of-sentence is determined by the same rules used for the end of the first sentence of class and member main descriptions.
Overview Comment File 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 Javadoc tool will merge into the overview page that it generates. 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 overview.html and place it anywhere, typically at the top level of the source tree. For example, if the source files for the java.applet package are contained in /home/user/src/java/applet directory, you could create an overview comment file at /home/user/src/overview.html.
Notice you can have multiple overview comment files for the same set of source files, in case you want to run javadoc multiple times on different sets of packages. For example, you could run javadoc once with -private for internal documentation and again without that option for public documentation. In this case, you could describe the documentation as public or internal in the first sentence of each overview comment file.
The content of the overview comment file is one big documentation comment, written in HTML, like the package comment file described previously. See that description for details. To re-iterate, 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 <body> and the first sentence. You can include overview tags; as with any documentation comment, all tags except in-line tags, such as {@link}, must appear after the main description. If you add a @see tag, it must have a fully-qualified name.
When you run the Javadoc tool, you specify the overview comment file name with the -overview option. The file is then processed similar to that of a package comment file.
o Copies all content between <body> and </body> tags for processing.
o Processes any overview tags that are present.
o Inserts the processed text at the bottom of the overview page it generates, as shown in Overview Summary @ http://docs.oracle.com/javase/7/docs/api/overview-summary.html.
o Copies the first sentence of the overview comment to the top of the overview summary page.
Miscellaneous Unprocessed Files You can also include in your source any miscellaneous files that you want the Javadoc tool to copy to the destination directory. These typically includes graphic files, example Java source (.java) and class (.class) 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 doc-files which can be a subdirectory of any package directory that contains source files. You can have one such subdirectory for each package. You might include images, example code, source files, .class files, applets and HTML files. For example, if you want to include the image of a button button.gif in the java.awt.Button class documentation, you place that file in the /home/user/src/java/awt/doc-files/ directory. Notice the doc-files directory should not be located at /home/user/src/java/doc-files because java 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 Javadoc tool does not look at the files -- it simply copies the directory and all its contents to the destination. For example, the link in the Button.java doc comment might look like: /** * This button looks like this: * <img src="doc-files/Button.gif"> */
Test Files and Template Files Some developers have indicated they want to store test files and templates files in the source tree near their corresponding source files. That is, they would like to put them in the same directory, or a subdirectory, 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 and prevent them from being processed. However, if you are passing in package names or wildcards, you need to follow certain rules to ensure these test files and templates files are not processed.
Test files differ from template files in that the former are legal, compilable source files, while the latter are not, but may end with ".java".
Test files - 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 package other than the source file package, such as the unnamed package (so the 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 specified 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 com.package1, 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 warnings.
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 passing in their test source filenames with wildcards, such as com/package1/test-files/*.java.
Templates 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 source files whose name, when stripped of the ".java" suffix, is actually a legal class name (see information about Identifiers in the Java Language Specification).
By default, javadoc uses a standard doclet that generates HTML-formatted documentation. This doclet generates the following kinds of files (where each HTML "page" corresponds to a separate file). Note that javadoc generates files with two types of names: those named after classes/interfaces, and those that are not (such as package-summary.html). Files in the latter group contain hyphens to prevent filename conflicts with those in the former group.
Basic Content Pages
o One class or interface page (classname.html) for each class or interface it is documenting.
o One package page (package-summary.html) for each package it is documenting. The Javadoc tool will include any HTML text provided in a file named package.html or package-info.java in the package directory of the source tree.
o One overview page (overview-summary.html) for the entire set of packages. This is the front page of the generated document. The Javadoc tool will include any HTML text provided in a file specified with the -overview option. Note that this file is created only if you pass into javadoc two or more package names. For further explanation, see HTML Frames.)
Cross-Reference Pages
o One class hierarchy page for the entire set of packages (overview-tree.html). To view this, click on "Overview" in the navigation bar, then click on "Tree".
o One class hierarchy page for each package (package-tree.html) 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 (package-use.html) and a separate one for each class and interface (class-use/classname.html). 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 (deprecated-list.html) 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 (constant-values.html) for the values of static fields.
o A serialized form page (serialized-form.html) for information about serializable and externalizable classes. Each such class has a description of its serialization fields and methods. This information 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 "Serialized Form" in the "See also" section of the class comment. The standard doclet automatically generates a serialized form page: any class (public or non-public) that implements Serializable is included, along with readObject and writeObject methods, the fields that are serialized, and the doc comments from the @serial, @serialField, 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 running javadoc without specifying the -private option.
o An index (index-*.html) 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).
o A help page (help-doc.html) that describes the navigation bar and the above pages. You can provide your own custom help file to override the default using -helpfile.
o One index.html file which 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 (*-frame.html) containing lists of packages, classes and interfaces, used when HTML frames are being displayed.
o A package list file (package-list), used by the -link and -linkoffline options. This is a text file, not HTML, and is not reachable through any links.
o A style sheet file (stylesheet.css) 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 Javadoc tool in any manner -- that is, any javadoc tags in them will be ignored. This directory is not generated unless it exists in the source tree.
HTML Frames
The Javadoc tool will generate either two or three HTML frames, as shown in the figure below. It creates the minimum necessary number of frames by omitting the list of packages if there is only one package (or no packages). That is, when you pass a single package name or source files (*.java) belonging to a single package as arguments into the javadoc command, it will create only one frame (C) in the left-hand column -- the list of classes. When you pass into javadoc two or more package names, it creates a third frame (P) listing all packages, as well as an overview page (Detail). This overview page has the filename overview-summary.html. 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 overview-summary.html.
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.
Load one of the following two files as the starting page depending on whether you want HTML frames or not:
o index.html (for frames)
o overview-summary.html (for no frames)
Generated File Structure
The generated class and interface files are organized in the same directory hierarchy that Java source files and class files are organized. This structure is one directory per subpackage.
For example, the document generated for the class java.applet.Applet class would be located at java/applet/Applet.html. The file structure for the java.applet package follows, given that the destination directory is named apidocs. 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 javadoc are source filenames (*.java) rather than package names. Also when arguments are source filenames, package-list is created but is empty. The doc-files directory will not be created in the destination unless it exists in the source tree.
apidocs                             Top directory index.html                       Initial page that sets up HTML frames * overview-summary.html            Lists all packages with first sentence summaries overview-tree.html               Lists class hierarchy for all packages deprecated-list.html             Lists deprecated API for all packages constant-values.html             Lists values of static fields for all packages serialized-form.html             Lists serialized form for all packages * overview-frame.html              Lists all packages, used in upper-left frame allclasses-frame.html            Lists all classes for all packages, used in lower-left frame help-doc.html                    Lists user help for how these pages are organized index-all.html                   Default index created without -splitindex option index-files                      Directory created with -splitindex option index-<number>.html          Index files created with -splitindex option package-list                     Lists package names, used only for resolving external refs stylesheet.css                   HTML style sheet for defining fonts, colors and positions java                             Package directory applet                       Subpackage directory Applet.html             Page for Applet class AppletContext.html      Page for AppletContext interface AppletStub.html         Page for AppletStub interface AudioClip.html          Page for AudioClip interface * package-summary.html    Lists classes with first sentence summaries for this package * package-frame.html      Lists classes in this package, used in lower left-hand frame * package-tree.html       Lists class hierarchy for this package package-use             Lists where this package is used doc-files               Directory holding image and example files class-use               Directory holding pages API is used Applet.html         Page for uses of Applet class AppletContext.html  Page for uses of AppletContext interface AppletStub.html     Page for uses of AppletStub interface AudioClip.html      Page for uses of AudioClip interface src-html                         Source code directory java                         Package directory applet                   Subpackage directory Applet.html         Page for Applet source code AppletContext.html  Page for AppletContext source code AppletStub.html     Page for AppletStub source code AudioClip.html      Page for AudioClip source code
Generated API Declarations The Javadoc tool generates a declaration at the start of each class, interface, field, constructor, and method description for that API item. For example, the declaration for the Boolean class is:
public final class Boolean extends Object implements Serializable
and the declaration for the Boolean.valueOfmethod is:
public static Boolean valueOf(String s)
The Javadoc tool can include the modifiers public, protected, private, abstract, final, static, transient, and volatile, but not synchronized or native. These last two modifiers are considered implementation detail and not part of the API specification.
Rather than relying on the keyword synchronized, APIs should document their concurrency semantics in the comment's main description, as in "a single Enumeration cannot be used by multiple threads concurrently". The document should not describe how to achieve these semantics. As another example, while Hashtable should be thread-safe, there's no reason to specify that we achieve this by synchronizing all of its exported methods. We should reserve the right to synchronize internally at the bucket level, thus offering higher concurrency.
The original "Documentation Comment Specification" can be found under related documentation.
Commenting the Source Code You can include documentation comments ("doc comments") in the source code, ahead of declarations for any class, interface, method, constructor, or field. 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 informally as "Javadoc comments" (but this term violates its trademark usage). 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 in a comment can continue onto multiple lines. /** * This is the typical format of a simple documentation comment * that spans two lines. */
To save space you can put a comment on one line: /** This comment takes up only one line. */
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 Javadoc tool.
A common mistake is to put an import statement between the class comment and the class declaration. Avoid this, as the Javadoc tool will ignore the class comment. /** * This is the class comment for the class Whatever. */
import com.sun;   // MISTAKE - Important not to put import statement here
public class Whatever { }
A doc comment is composed of a main description followed by a tag section - The main description begins after the starting delimiter /** and continues until the tag section. The tag section starts with the first block tag, which is defined by the first @ character that begins a line (ignoring leading asterisks, white space, and leading separator /**). It is possible to have a comment with only a tag section and no main description. The main description cannot continue 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. For example, this @see starts the tag section: /** * This sentence would hold the main description for this doc comment. * @see java.lang.Object */
Block tags and in-line tags - A tag is a special keyword within a doc comment that the Javadoc tool can process. There are two kinds of tags: block tags, which appear as @tag (also known as "standalone tags"), and in-line tags, which appear within curly braces, as {@tag}. To be interpreted, a block tag must appear at the beginning of a line, ignoring leading asterisks, white space, and separator (/**). This means you can use the @ character elsewhere 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 &#064;. Each block tag has associated 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 contains the block tag @deprecated and in-line tag {@link}. /** * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */
Comments are written in HTML - The text must be written in HTML, in that they should use HTML entities and can use HTML tags. You can use whichever version of HTML your browser supports; we have written the standard 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 (>) symbols should be written < and >. Likewise, the ampersand (&) should be written &. The bold HTML tag <b> is shown in the following example.
Here is a doc comment: /** * This is a <b>doc</b> comment. * @see java.lang.Object */
Leading asterisks - When javadoc parses a doc comment, leading asterisk (*) characters on each line are discarded; blanks and tabs preceding the initial asterisk (*) characters are also discarded. Starting with 1.4, if you omit the leading asterisk on a line, the leading white space is no longer removed. This enables you to paste code examples directly into a doc comment inside a <PRE> tag, and its indentation will be honored. Spaces are generally interpreted by browsers more uniformly than tabs. Indentation is relative to the left margin (rather than the separator /** or <PRE> 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 followed by a blank, tab, or line terminator, or at the first block tag. The Javadoc tool copies this first sentence to the member summary at the top of the HTML page.
Declaration with multiple fields - Java allows declaring multiple fields in a single statement, but this statement can have only one documentation 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 documentation comment doesn't make sense written as a single declaration and would be better handled as two declarations: /** * The horizontal and vertical distances of point (x,y) */ public int x, y;      // Avoid this
The Javadoc tool generates the following documentation from the above code: public int x The horizontal and vertical distances of point (x,y) public int y The horizontal and vertical distances of point (x,y)