JavadocTemplateTutorial

JavadocTemplatesTutorial

This tutorial guides you using the javadoc-template plugin.

Contents 1 JavadocTemplatesTutorial 1.1 Introduction 1.2 Steps to Reproduce 1.3 Creating A Overview Document 1.4 Creating A Package Document 1.5 Creating A Stylesheet 1.6 Packaging Configurations 1.7 Expected Result

Introduction

The javadoc-template plugin offers templates for writing and using javadoc documents.

It offers templates for writing following javadoc documents:

• overview.html templates - documentation of the entire application, the set of packages
• package.html templates - documentation of a single package
• javadoc.css templates - stylesheet of the generated javadoc html pages

Using the javadoc-template plugin helps you to have a consistent javadoc documentation within your project, and across your various projects.

Steps to Reproduce

• Download the javadoc-template plugin from http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=1168
• Select a template from the template wizard category Javadoc.
• Select an appropriate file name for the template created file.
• Edit the created package, and overview documents.
• Configure your project settings for using an overview document, and using javadoc style-sheet.
• View your javadoc project documentation.

The wizard page for selecting a javadoc template looks like the screen shot below:
http://wiki.netbeans.org/attach/JavadocTemplateTutorial/javadoc-template-new_JavadocTemplateTutorial.gif

Creating A Overview Document

Create an overview document for your java documentation.

• Select a folder for your overview document. Usually the source default package is a good candidate.
• Invoke the File|New File.., alternativly select New from the context-menu.
• Navigate to the template category Javadoc|Overview.
• Select an overview template
• Choose a file name for the overview document. Usually a file name overview is a good candidate.
• Open the created overview document, and edit the content of this file to your specific needs.
• Finish the wizard

Using the created overview file, configure javadoc to use the created overview file. If you have created an overview documentation, you have to tell javadoc to use your overview document. In Ant's build.xml augment the javadoc task by specifying the overview file, like:

    <javadoc...
    overview="${path-to-overview}/overview.html"...
    > 

Alternatively specify in your project Properties|Documenting the overview document in the field Additional javadoc options, like:

    -overview=${basedir}/${src.dir}/overview.html 

Creating A Package Document

Create a package document for your java package documentation.

• Select a package for your package document.
• Invoke the File|New File.., alternativly select New from the context-menu.
• Navigate to the template category Javadoc|Package.
• Select a package template
• Choose the file name package for the package document.
• Open the created package document, and edit the content of this file to your specific needs.
• Finish the wizard

The javadoc tool accepts files named package.html automatically as package documentation. Thus no extra configuration is necessary for including the package documentation in the javadoc generated html pages.

Creating A Stylesheet

Create an stylesheet document for your java documentation.

• Select a folder for your overview document. Usually the source default package is a good candidate.
• Invoke the File|New File.., alternativly select New from the context-menu.
• Navigate to the template category Javadoc|Style.
• Select a stylesheet template
• Choose a file name for the stylesheet document. Usually a file name javadoc is a good candidate.
• Open the created overview document, and edit the content of this file to your specific needs.
• Finish the wizard

If you have created a javadoc style sheet, you have to tell javadoc to use your style sheet file. In Ant's build.xml augment the javadoc task by specifying the style sheet file, like:

    <javadoc...
    stylesheetfile="${path-to-javadoc-style sheet}/javadoc.css"
    ...
    > 

Alternatively specify in your project Properties|Documenting the style sheet file in the field Additional javadoc options, like:

    -stylesheetfile=${basedir}/${src.dir}/stylesheet.css 

Packaging Configurations

Don't forget to exclude the javadoc files from copying into the build directory. Simply add them to field Exclude From Jar File in the project properties dialog Build|Packaging, like:

    :*/*.java,**/*.form,**/package.html,overview.html,javadoc.css 

Expected Result

After running javadoc your java documentation has:

• An overview documentation
• A package documentation for each package
• A CSS stylesheet specifying the visuale aspect of the java documentation

The package documentation looks like:
http://wiki.netbeans.org/attach/JavadocTemplateTutorial/javadoc-templates-result_JavadocTemplateTutorial.gif

The class documentation looks like:
http://wiki.netbeans.org/attach/JavadocTemplateTutorial/javadoc-templates-result-2_JavadocTemplateTutorial.gif

• This page was last modified on 5 November 2009, at 12:35.
• This page has been accessed 309 times.