Home arrow Java arrow Page 2 - Using Javadoc

Using Javadoc

JavaThe Stat Data Provider Inc. development team scours their code and frantically attempts to piece together a development guide. Unfortunately, they have forgotten the details of how certain portions work. The Javadoc(TM) tool can deter such a situation from showing its ugly face. In this article, the reader is guided through self-documenting code in a structured manner to generate Java(TM) API documentation.

Author Info:
By: Kulvir Singh Bhogal & Kwang Sik Kang
Rating: 3 stars3 stars3 stars3 stars3 stars / 38
January 07, 2004
  1. · Using Javadoc
  2. · Java Documentation Comments
  3. · A Sample Class with Some Comments
  4. · Taking a Peek at the Automagically Generated Documentation
  5. · Conclusion

print this article

Using Javadoc - Java Documentation Comments
(Page 2 of 5 )

Java provides a documentation comment taking the format found in Listing 1. Javadoc comments are used to describe classes, variables, objects, and methods.  A Javadoc comment is placed above the element it is documenting. 

Listing 1: JavaDoc Comment

Line 1: /** Description of the element being documented
Line 2: * @tagA Description of tagA
Line 3: * @tagB Description of tagB
Line 4: */

There are a few elements to notice in the snippet above. The first is the beginning of the Java documentation comment begins with /** (Line 1) and ends with */ (Line 4).

Next, as the code snippet states, the first part of the comment should describe the documented element (Line 1). The upcoming exercise will illustrate the Javadoc tool’s interpretation of this description.

Finally, note the presence of tags in the code snippet (Lines 2 & 3). There are a number of predefined tags that can be used to describe a given element.  Some of these include:

@author text – the element’s author (only used for Java classes)

@version text – the element’s version number (only used for Java classes)

@param name description – describes the parameters of a method accompanied by a description (used for Java methods)

@return text – describes the value returned by a method (used for Java methods)

@exception exceptionClassName description – states the exceptions that a given method throws with an associated description.

@deprecated – used to state that the element being described has been deprecated.  When you use this tag, a deprecation warning will be issued when you compile a Java program using the element in question.

@since text – describes the product version when the element was added to the API specification

Note that there are a number of other tags that we have not discussed.  A good resource to learn more about all the tags in your Javadoc arsenal is the How to Write Doc Comments for the Javadoc Tool reference.

blog comments powered by Disqus

- Java Too Insecure, Says Microsoft Researcher
- Google Beats Oracle in Java Ruling
- Deploying Multiple Java Applets as One
- Deploying Java Applets
- Understanding Deployment Frameworks
- Database Programming in Java Using JDBC
- Extension Interfaces and SAX
- Entities, Handlers and SAX
- Advanced SAX
- Conversions and Java Print Streams
- Formatters and Java Print Streams
- Java Print Streams
- Wildcards, Arrays, and Generics in Java
- Wildcards and Generic Methods in Java
- Finishing the Project: Java Web Development ...

Watch our Tech Videos 
Dev Articles Forums 
 RSS  Articles
 RSS  Forums
 RSS  All Feeds
Write For Us 
Weekly Newsletter
Developer Updates  
Free Website Content 
Contact Us 
Site Map 
Privacy Policy 

Developer Shed Affiliates


© 2003-2019 by Developer Shed. All rights reserved. DS Cluster - Follow our Sitemap
Popular Web Development Topics
All Web Development Tutorials