1. Javadoc Guide
  2. Source Files

2 Source Files

The javadoc tool generates output that originates from the following types of source files: Java language source files for classes (.java), package comment files, overview comment files, and miscellaneous unprocessed files.

This topic describes source files, test files, and template files that can also be in the source tree, but that must be sure not to document.

Class Source Files

The source file of each class can have their own documentation comments.

Overview Comment Files

Each application or set of packages that you’re documenting can have its own overview documentation comment that's kept in its own source file, which the javadoc tool then merges into the generated overview page. You typically include in this comment any documentation that applies to the entire application or set of packages.

You can name the file anything that you want, such as overview.html and place it anywhere. A typical location is at the top of the source tree.

Oracle Solaris, Linux, and macOS: For example, if the source files for the java.math package are contained in the /home/user/src/java/math directory, then you could create an overview comment file in /home/user/src/overview.html.

Windows: For example, if the source files for the java.math package are contained in the C:\user\src\java\math directory, then you could create an overview comment file in C:\user\src\overview.html.

You can have multiple overview comment files for the same set of source files in case you want to run the javadoc tool multiple times on different sets of packages. For example, you could run the javadoc tool once with -private option 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 that's written in HTML. Make the first sentence a summary about the application or set of packages. Don't put a title or any other text between the <body> tag and the first sentence. All tags, except inline tags, such as an {@link} tag, must appear after the main description. If you add an @see tag, then it must have a fully qualified name.

When you run the javadoc tool, specify the overview comment file name with the -overview option. The file is then processed similarly to that of a package comment file. The javadoc tool does the following:

  • Copies all content between the <body> and </body> tags for processing.

  • Processes the overview tags that are present.

  • Inserts the processed text at the bottom of the generated overview page.

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

Unprocessed Files

Your source files can include any files that you want the javadoc tool to copy to the destination directory. These files usually include graphic files, example Java source and class files, and self standing HTML files with a lot of content that would overwhelm the documentation comment of a typical Java source file.

To include unprocessed files, put them in a directory called doc-files. The doc-files directory can be a subdirectory of any package directory that contains source files. You can have one doc-files subdirectory for each package.

Oracle Solaris, Linux, and macOS: For example, if you want to include the image of a button in the java.awt.Button class documentation, then place the image file in the /home/user/src/java/awt/doc-files/ directory. Don't place the doc-files directory at /home/user/src/java/doc-files, because java isn't a package. It doesn't contain any source files.

Windows: For example, if you want to include the image of a button in the java.awt.Button class documentation, then place the image file in the \src\java\awt\doc-files directory. Don't place the doc-files directory at \src\java\doc-files, because java is not a package. It doesn't contain any source files.

All links to the unprocessed files must be included in the code because the javadoc tool doesn't look at the files. The javadoc tool copies the directory and all of its contents to the destination. The following example shows how the link in the Button.java documentation comment might look: 

/**
 * <p> This button looks like this:</p> 
 * <img src="doc-files/Button.gif"/>
 */
Test and Template Files

You can store test and template files in the source tree in the same directory with or in a subdirectory of the directory where the source files reside. To prevent test and template files from being processed, run the javadoc tool and explicitly pass in individual source file names.

Test files are valid, compilable source files. Template files aren’t valid, compatible source files, but they often have the .java suffix.

  • Test Files : If you want your test files to belong to either an unnamed package or to a package other than the package that the source files are in, then put the test files in a subdirectory underneath the source files and give the directory an invalid name. If you put the test files in the same directory with the source files and call the javadoc tool with a command-line argument that indicates its package name, then the test files cause warnings or errors. If the files are in a subdirectory with an invalid name, then the test file directory is skipped and no errors or warnings are issued. For example, to add test files for source files in com.package1, put them in a subdirectory in an invalid package name. The following directory name is invalid because it contains a hyphen:

    • Oracle Solaris, Linux, and macOS: com/package1/test-files/

    • Windows: com\package1\test-files\

    If your test files contain documentation comments, then you can set up a separate run of the javadoc tool to produce test file documentation by passing in their test source file names with wild cards, such as com/package1/test-files/*.java.

  • Template Files : If you want a template file to be in the source directory, but not generate errors when you execute the javadoc tool, then give it an invalid file name such as Buffer-Template.java to prevent it from being processed. The javadoc tool processes only source files with names, when stripped of the .java suffix, that are valid class names.

Processing the Package Comment File

When the javadoc tool runs, it searches for the package comment file. If the package comment file is found, then the javadoc tool does the following:

  • Copies the comment for processing. For package.html, the javadoc tool copies all content between the <body> and </body> HTML tags. You can include a <head> section to put a <title> tag, source file copyright statement, or other information, but none of these appears in the generated documentation.

  • Processes the package tags.

  • Inserts the processed text at the bottom of the generated package summary page.

  • Copies the first sentence of the package comment to the top of the package summary page. The javadoc tool also adds the package name and this first sentence to the list of packages on the overview page.

    The end of the sentence is determined by the rules used for the end of the first sentence of class and member main descriptions.