Document! X 2022
Documentation Types / Java Reference Documentation
In This Topic
    Java Reference Documentation
    In This Topic

    The Java documentation support in Document! X allows you to create documentation for your Java source code projects.

    A full documentation set is generated including pages for each class, interface, enumeration, constructor, method, and field you choose to include. Inheritance hierarchies, cross topic links, Object Model diagrams, and Syntax sections are all automatically generated and combined with content from Javadoc source comments and any additional content you choose to author in a Document! X Content File.

    The Document! X Java Documentation support fully leverages Javadoc source comments, adding features and functionality to what is possible with the Standard Javadoc generator.

    Java Reference Documentation Fundamentals

    Create a New Java Reference Documentation Project

    Create an Empty Project

    Creating an empty project creates a project without any content. You can customize its settings according to your needs.

    To create an empty project:

    1. Click the Application Button at the upper-left of the Ribbon Menu.
    2. Click New and then select Empty Project.

       

    3. Enter a project name in the Project Name field. 
      The project is created at the default directory which is configurable in the Options Editor (Paths page). However, you can optionally choose a specific directory to save your project by browsing the Project Directory field.
             
    4. Click OK.

    The new empty documentation project is created and opened for edit. You can now add the Java Projects that you wish to document:

    1. On the Project tab, click the Add Java Project option.
    2. Use the displayed dialog to define the source location, package names, and other properties of the Java Project you would like to document in this project.

    The selected Java Project is added to the Project Explorer under the Java Projects node. You can expand down through each project node to select/deselect individual packages or types in order to include / exclude them from the generated output; by default private and protected types are excluded (cleared).

    You can add as many additional Java Projects as you wish by repeating the procedure above.

    A Content File is created and added to the project under the Content Files node for each Java Project you add to the project. You can use this Content File to author additional content in the pages that Document! X automatically generates.

    Javadoc Comments from your source code are automatically used in the generated output. Javadoc content is displayed in the Content File Editor so you can see at a glance what content is already available from source comments and what requires further authoring.
           

    Author Content in Javadoc Comments

    You can use standard Javadoc source comments in your Java source code and Document! X uses them by default in the generated output.

    Example

    /**
     * <p>Returns an Image object that can then be painted on the screen.
     * The url argument must specify an absolute {@link URL}. The name
     * argument is a specifier that is relative to the url argument.</p>
     * <p>This method always returns immediately, whether or not the
     * image exists. When this applet attempts to draw the image on
     * the screen, the data will be loaded. The graphics primitives
     * that draw the image will incrementally paint on the screen.</p>
     *  
     * @param  url  an absolute URL giving the base location of the image
     * @param  name the location of the image, relative to the url argument
     * @return      the image at the specified URL
     * @see  Image
     */
     public Image getImage(URL url, String name) {
            try {
                return getImage(new URL(url, name));
            } catch (MalformedURLException e) {
                return null;
            }
     }
    Each time you load your project, Document! X will extract the latest Javadoc source comments for use in the documentation generation process so your documentation is always right up-to-date.

       See Author Content using the Content File Editor  for authoring outside of the source code.

    Author content outside of the source code

    If you would like to supplement the content of the pages automatically generated by Document! X and HelpStudio outside of the source code, you can do so using the Document! X and HelpStudio Content File Editor.

    The Content File Editor allows you to review and author content for any item for which a reference documentation page is generated.

    To open the Content File Editor:

    1. Expand the Content Files node on the Project Explorer.
    2. Locate the Content File for the item you wish to author content for.
    3. Right-click the Content File and select Edit.
    4. The Content File opened for edit. The tree on the left side of the editor shows you a hierarchical view of the item you are documenting.
    5. Drill down and select an item from the tree and the related documentation pages are shown in the right side of the editor.
    6. Select a specific content type from the toolbar/vertical menu to edit a specific type of content, for example, Summary, See Also, and Keywords.
    7. Type directly in the editable portions of the page on the right side of the editor.

    Add Conceptual Topics

    Conceptual information is a key part of reference documentation, providing a high level introduction, tutorials, or other conceptual information. You can easily create conceptual topics in Document! X.

    1. Click the New Topic button on the Project tab or use the Ctrl+T shortcut key.
    2. The new Topic is created in the currently-selected Topic Category on the Project Explorer (or under the (Un-categorized) node if no category is selected) and opened for edit.

       

    3. Enter your conceptual content directly in the editable area of the Topic Editor.

    You can find more information on Topic Editing in the Topic Editor topic.

    Change Java Documentation Settings

    The settings that govern Java documentation generation are defined in the Build Profile editor. In a new project there is a single Build Profile but you can define many build profiles if you want to create multiple outputs with different settings.

    To edit Java documentation settings:

    1. On the Project Explorer, expand the Build Profiles node.
    2. Double-click the required Build Profile to edit the properties.
      Alternatively, you can also right-click the required Build Profile and select Edit to open the Build Profile editor.

    In the Build Profile editor, you can find the Java Settings pages under the Reference Documentation section.

    You can change the Template used for Java documentation (which defines the look and feel of generated pages) on the Templates page.

           

    Identify Undocumented Items

     An essential part of delivering a complete documentation set is ensuring that all the items have been documented. Document! X includes the Undocumented Items tool to quickly and easily identify undocumented items.

    1. On the Tools tab, select the Undocumented Items option.
    2. Select the profile in the Project Profile field for which you want to find the undocumented items.
      If your project contains only one Build Profile then it appears in the Project Profile field by default.
    3. Select Item Types, for example, Class, Method, Schema, and Column, that you want to check for undocumented items.
    4. Select Content Types to indicate the items that must be considered documented (just Summary by default).
    5. Select the Content Sources that should be used when checking for content.
    6. Select Execute. Any undocumented items will be listed in the results grid.

    Build and Deploy Java Reference Documentation

    On the Project tab, click the  Build button to build your Java Reference Documentation.

    In a new project, the default Build Profile is configured to generate output in CHM Html Help 1.x format. You can define additional Build Profiles if you want to generate multiple output types.
    You can modify the Build Profile settings to specify the Java settings such as the content options, Java member filters, Java type filters, link options, and so on.

    Java documentation generated by Document! X can be published and associated with your Java Projects in Java Development tools in order to drive both tooltip and Shift+F1 help functionality, thereby providing developments who use your Java Projects with instant access to the documentation.

    Refer to the Deploying Java Documentation topic for more information on publishing your Java documentation.

    See Also

    Root Topics