8/11/2019 Lecture 03 - Java_doc
1/22
JavaDoc 1
JavaDoc
8/11/2019 Lecture 03 - Java_doc
2/22
JavaDoc 2
Outline
What is JavaDoc?
JavaDoc CommentsJavaDoc TagsGenerating JavaDoc DocumentationReferences
8/11/2019 Lecture 03 - Java_doc
3/22
JavaDoc 3
What is JavaDoc?
A software tool developed by Sun Microsystems forgenerating API documentation format from Java sourcecode augmented with special tags in the codes comments.An industry standard for documenting Java classes.
How does JavaDoc work?Instead of writing and maintaining separatedocumentation, the programmer writes formatted
comments in the Java code itself.Javadoc takes these comments and transforms theminto documentation.
8/11/2019 Lecture 03 - Java_doc
4/22
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 itcan generate documentation for various programminglanguages and generate output in various formats.
8/11/2019 Lecture 03 - Java_doc
5/22
JavaDoc 5
What is JavaDoc?
Advantages:Program documentation process is coupled with the
programming processAutomated generation of documentation: less error-proneEase of generation of documentation
Ease of update of documentationShort code-to-documentation cycle: all programmers can bemade aware of others developments almost in real timeCan generate highly browsable documentation, accessible
electronically over the web (HTML)
8/11/2019 Lecture 03 - Java_doc
6/22
JavaDoc 6
What is JavaDoc?
Disadvantages:There is a learning curve to learn how to use the tool,though it is minimalRequires dedication, or else the documentation will beobsolete or incomplete.
8/11/2019 Lecture 03 - Java_doc
7/22
JavaDoc 7
What is JavaDoc?
Example:
8/11/2019 Lecture 03 - Java_doc
8/22
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 upunder the first asterisk in the first line.
/*** This is a javadoc comment.*/
Because JavaDoc generates HTML files, any valid HTML can beembedded. A JavaDoc comment may be composed of multiplelines, for example:
/*** This is line one.* This is line two.** This is intended as a new paragraph.*/
8/11/2019 Lecture 03 - Java_doc
9/22
JavaDoc 9
JavaDoc Comments
A JavaDoc comment is written in HTML and must precede aclass , field , constructor or method declaration.The * character is a marker used to make the JavaDoc commentsmore readable in the source file. They will not appear in thegenerated HTML documents. Since the blanks and tabs are alsoremoved, we need to use an HTML tag
to mark a new
paragraph as in: /**
* This is paragraph one.**
* This is paragraph two.**
* This is the last paragraph.
*/
8/11/2019 Lecture 03 - Java_doc
10/22
JavaDoc 10
JavaDoc Comments
Another useful HTML marker is , which we can use toinclude a sample code in a JavaDoc comment. Any text betweenthe and markers will appear in a Courier font.
Example:
8/11/2019 Lecture 03 - Java_doc
11/22
JavaDoc 11
JavaDoc Comments
The generated HTML will be:
8/11/2019 Lecture 03 - Java_doc
12/22
JavaDoc 12
JavaDoc Comments
For the JavaDoc comments to be recognized as such by the javadoc tool, they must appear immediately before the class,interface, constructor, method, or data member declarations.If you put the JavaDoc comment for the class before the importstatements, it will be ignored .The first sentence is a summary sentence . This should be ashort description of the element described by the comment.
Note: JavaDoc does not provide a format for commenting elementswithin methods, i.e. the local variables and the computing goingon inside the methods. But you still can use the regular commentsmarks // or /*..*/, to comment this part of your program.
8/11/2019 Lecture 03 - Java_doc
13/22
JavaDoc 13
JavaDoc Tags
Special tags can be embedded within the JavaDoc comments.These tags start with the at symbol @ .
JavaDoc tags must start at the beginning of a line.
Example:
8/11/2019 Lecture 03 - Java_doc
14/22
JavaDoc 14
JavaDoc Tags
@authorUse this tag to create an author entry. You can have multiple@author tags. This tag is meaningful only for the class/interface JavaDoc comment.
@versionUse this tag to create a version entry. A JavaDoc comment maycontain at most one @version tag. Version normally refers to theversion of the software (such as the JDK) that contains thisfeature.
@seeUse this tag to add a hyperlinked "See Also" entry to the class.
8/11/2019 Lecture 03 - Java_doc
15/22
JavaDoc 15
JavaDoc Tags
Example:
8/11/2019 Lecture 03 - Java_doc
16/22
JavaDoc 16
JavaDoc Tags
Generated HTML:
8/11/2019 Lecture 03 - Java_doc
17/22
JavaDoc 17
JavaDoc Tags
@paramUse this tag to add a parameter description for a method. This tag
contains two parts: the first is the name of the parameter and thesecond is the description. The description can be more than one line.
@param size the length of the passed array
@returnUse this tag to add a return type description for a method. This
tag is meaningful only if the methods return is non-void.
@return true if the array is empty; otherwise return false
8/11/2019 Lecture 03 - Java_doc
18/22
JavaDoc 18
JavaDoc Tags
Example:
8/11/2019 Lecture 03 - Java_doc
19/22
JavaDoc 19
JavaDoc Tags
Generated HTML:
8/11/2019 Lecture 03 - Java_doc
20/22
JavaDoc 20
Generating JavaDoc DocumentationAfter 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 themandatory ones are either the packages name or the source filename.
Example:In order to enforce JavaDoc to generate documentation for the completeGIPSY package, we write:
javadoc gipsy
In order to enforce JavaDoc to generate documentation for theJINITransportAgent.java file, to include the author and version tag and toinclude all the classes, attributes and methods we write:
javadoc -private -version -author JINITransportAgent.java
8/11/2019 Lecture 03 - Java_doc
21/22
JavaDoc 21
Generating JavaDoc Documentation
Example:
The source java file with built in JavaDoc documentation:JINITransportAgent.java
The generated HTML documentation:JINITransportAgent.html
http://c/Documents%20and%20Settings/paquet/Desktop/javadoc/JINITransportAgent.javahttp://c/Documents%20and%20Settings/paquet/Desktop/javadoc/JINITA_doc/index.htmlhttp://c/Documents%20and%20Settings/paquet/Desktop/javadoc/JINITA_doc/index.htmlhttp://c/Documents%20and%20Settings/paquet/Desktop/javadoc/JINITransportAgent.java8/11/2019 Lecture 03 - Java_doc
22/22
JavaDoc 22
Sun Microsystems, How to Write Doc Comments for the Javadoc Tool ,http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
Emil Vassev, DMS API Documentation, Concordia University, Montreal,Quebec, Canada, 2005
Wikipedia. Comparison of Documentation Generators.http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
References