JavaDoc: Generating API Documentation from Java Source Code, Slides of Java Programming

Download JavaDoc: Generating API Documentation from Java Source Code and more Slides Java Programming in PDF only on Docsity!

JavaDoc 1

JavaDoc

July 24, 2006

revision 1.2 – Jan 26, 2009

JavaDoc 2

Outline

 What is JavaDoc?  JavaDoc Comments  JavaDoc Tags  Generating JavaDoc Documentation  References

JavaDoc 4

What is JavaDoc?

 Many such systems exist that can be used for various

programming languages:

 Javadoc, Doxygen, …

 Many of these can output in different formats:

 HTML, RTF, PDF, LaTeX, manpages, …

 HTML has many advantages:

 Portable, browsable, adaptable

 Doxygen is probably the most flexible of them all, as it

can generate documentation for various programming

languages and generate output in various formats.

JavaDoc 5

What is JavaDoc?

 Advantages:

 Program documentation process is coupled with the programming process  Automated generation of documentation: less error-prone  Ease of generation of documentation  Ease of update of documentation  Short code-to-documentation cycle: all programmers can be made aware of others’ developments almost in real time  Can generate highly browsable documentation, accessible electronically over the web (HTML)

JavaDoc 7

What is JavaDoc?

Example:

JavaDoc 8

JavaDoc Comments

 A JavaDoc comment begins with the **/**** marker and ends with the */ marker. All the lines in the middle start with an asterisk lined up under the first asterisk in the first line. /

• This is a javadoc comment. /*

 Because JavaDoc generates HTML files, any valid HTML can be embedded. A JavaDoc comment may be composed of multiple lines, for example: /

• This is line one.
• This is line two.
• This is intended as a new paragraph. /*

JavaDoc 10

JavaDoc Comments

 Another useful HTML marker is **** , which we can use to include a sample code in a JavaDoc comment. Any text between the **** and **** markers will appear in a Courier font.

Example:

JavaDoc 11

JavaDoc Comments

The generated HTML will be:

JavaDoc 13

JavaDoc Tags

 There are a number of special tags we can embed with the JavaDoc comments. These tags start with the “at” symbol @.

 JavaDoc tags must start at the beginning of a line.

Example:

JavaDoc 14

JavaDoc Tags

@author

Use this tag to create an author entry. You can have multiple @author tags. This tag is meaningful only for the class/interface JavaDoc comment.

@version

Use this tag to create a version entry. A JavaDoc comment may contain at most one @version tag. Version normally refers to the version of the software (such as the JDK) that contains this feature.

@see

Use this tag to add a hyperlinked "See Also" entry to the class.

JavaDoc 16

JavaDoc Tags

Generated HTML:

JavaDoc 17

JavaDoc Tags

@param

Use this tag to add a parameter description for a method. This tag contains two parts: the first is the name of the parameter and the second is the description. The description can be more than one line.

@param size the length of the passed array

@return

Use this tag to add a return type description for a method. This tag is meaningful only if the method’s return is non-void.

@return true if the array is empty; otherwise return false

JavaDoc 19

JavaDoc Tags

Generated HTML:

JavaDoc 20

Generating JavaDoc Documentation

 After adding the JavaDoc comments to the source files, we use the javadoc command to generate the documentation.

 We run the javadoc as we run javac or java tools.

 After the javadoc command, we provide the parameters, when the mandatory ones are the either the package’s name or the source file (s) name.

Example:

In order to enforce JavaDoc to generate documentation for the complete GIPSY package, we write: javadoc gipsy

In order to enforce JavaDoc to generate documentation for the JINITransportAgent.java file, to include the author and version tag and to include all the classes, attributes and methods we write: javadoc -private -version -author JINITransportAgent.java