digitization, transformation, binary

Java Documentation Generator-JavaDoc

To use the API effectively, we need good documentation. In java, it is always not about writing the code but also about the documentation of our code so that the users of the code can understand in detail without going through the code.

Static documentation faces challenges of maintenance. If we change the code in, generally we have to update the documentation. If documentation and code are different, it becomes an overhead to maintain it, whenever code changes. The best solution is to put everything in the same file but that needs some syntax to mark special documentation and a tool to extract those comments and put them in a useful form.

In java, the tool that extracts comments is called JavaDoc. The documentation for most java APIs is prepared using Javadoc. It extracts the comments, class, method names, etc from the source file itself. The output of the JavaDoc is an HTML file that can be seen in a web browser.

This tool allows us to create and maintain a single source file and generates the documentation automatically. So JavaDoc is a tool that reads source code files, extracts JavaDoc comments and creates a set of webpages containing comments in a nicely formatted and interlinked form. Javadoc takes the syntactic information to add semantics and pragmatics.

The class documentation files that JavaDoc generates describe the class (or interface) and its inheritance hierarchy, and index and describe each of the public and protected members of the class.

The generated file also contains any “doc comments” that are associated with the class and with its methods, constructors, and variables. A ” doc comment or documentation comment, is a Java comment that begins with/ * * and ends with */.

A doc comment may include any HTML markup tags (although it should not include structuring tags like < HI > or < HR >), and may also include tag values that are treated specially by JavaDoc.

By default, JavaDoc will only collect information about public classes, public subroutines, and public members variables, but it also allows an option to create documentation for non-public things as well.
If JavaDoc does not find any JavaDoc comments for a source file, it will create one with very basic information like- name, type of member variables, return types, parameter lists of the method, etc.
Syntax of JavaDoc
JavaDoc comments are placed just before the subroutine for which we are commenting on. All the Javadoc commands start with /** and end with */. There are two ways to create JavaDoc. They are as follows:

  • Use doc tags
  • Embedded HTML

The equivalent syntax to generate JavaDoc are as follows:

javadoc [options] packageName
javadoc [options] fileName

When a package name is specified on a command line, JavaDoc looks for a corresponding package directory relative to the CLASSPATH. It then parses the .java source file in the directory and generates an HTML document for each class and an HTML index of the classes in the package. By default, the HTML files are placed in the current directory. The -d option allows us to override the default.

Here the packageName argument to JavaDoc is the name of the package but not the name of the package directory. We can specify the -sourcepath option so that java can find our package source.

JavaDoc can be invoked with any number of java source files provided in the command line. Remember they are file names but not the .class names.

READ  All About Class URLEncode in Java

Doctags:
Doc tags are passed to the JavaDoc tool. Doc tags are commands that starts with a ‘@’ and are placed at the beginning of the comment line. A leading star(*) is ignored or *s at the beginning of lines are optional.

The Javadoc tool will remove them. This rule is always followed. Like any other comment, JavaDoc comments are ignored by the compiler when it is compiled.Doc comments should immediately precede the deceleration of the class, field or method that is associated with it.

The first sentence of a doc comment should be a summary sentence, suitable for display. The next few lines of sentences may document the feature in detail. The text that follows a tag may span multi-lines and continue until the next JavaDoc tag or JavaDoc end tag is encountered.

Doctag commands are like

@param =>description of the parameters
@return =>description of the return values
@throws =>descriptions of the exceptions

Descriptions can be of several lines. The description ends at the next tag or the end of the comment.

Comments are a special section of the text inside a program. Its purpose is to help people understand the program. A comment is part of good programming documentation.

Javadoc supports multiple comment styles:

  • // single line comment-End line comment
  • /** ….*/ multiple line comments -JavaDoc comments
  • /*……*/ old-style multi-line comments-traditional comment

No text inside the comment gets handled by the compiler. There are three types of comment documentation which corresponds to the element that comment precedes. They are as follows:

  • Class
  • Variable
  • Method

Class comment:
A class comment appears right before the definition of a class.

/** A class comment*/
public class Aclass{} 

Variable comment:
A variable comment appears right in front of the definition of a variable.

/** A variable comment*/
public int sizeOfString;

Method comment:
A method comment appears right in front of the definition of the method.

/** A method comment*/
public int getValue(){} 

Javadoc processes comment documentation for public and protected members only. Comments of private and friendly members are ignored. They produce no output. All class comments are included in the output.
@see:refer to other classes/method/variables:
All three of the comment documentation can contain @see tags which allow us to refer to the documentation in other classes. JavaDoc will generate HTML having a @see tags hyperlinked to other [email protected] -creates a hyperlink to the specified class, It may be used before classes, methods or fields,

@see classname
@see fully_qualified_clasname
@see filly_qualified_classname#methodname 

Each one adds a hyperlinked “see also” entry to the generated documentation. JavaDoc will not check the validation of the hyperlinks.
class documentation tags:
Class documentation may also contain the below tags along with the @see tag. @see -creates a hyperlink to the specified class, It may be used before classes, methods or fields

@see classname
@version-version information(when version information is placed on the JavaDoc command line, the version information will be called out especially in the generated HTML).It is mostly applicable to the class definition.
JavaDoc ignores this tag until -version command-line argument is specified.
@author-This tag adds an "Author:" entry in the documentation. author information like name, email id, etc will be placed on the JavaDoc command line, the author information will be called out especially in the generated HTML).
If we have multiple authors, they must be placed consecutively. They will be placed in a single paragraph. This 
entry is ignored by JavaDoc until -author command line argument specified. 

Variable documentation tags:
This can only include embedded HTML and @see [email protected] -creates a hyperlink to the specified class, It may be used before classes, methods or fields
Method documentation tags:
Along with @see tag, the below written are also supported:@see -creates a hyperlink to the specified class, It may be used before classes, methods or fields

@param- This tag adds an entry as "Parameter:" in the documentation.it says the parameter name description where parameter name is the identifier in the parameter list and the description is considered finished
when a new documentation tag is encountered. We can have any number of these, presumably one for each parameter.
it may roll over to multiple lines.
@return- This tag adds a "Returns:" section in the documentation here the description talks about the meaning of these values. It can continue on subsequent lines.
@exception-This tag adds a "Throws:" section in the documentation. Fully qualified class name description which gives us an unambiguous name of the exception class that is defined somewhere and the description tells us why this particular type of exception can emerge from the method call. It can continue on subsequent lines. This should signify the exception. Mostly used in method context.
@deprecated-This tag adds a "Deprecated:" section-in the documentation. It is used to tag features that 
have been suspended by an improved feature. The deprecated tag is a suggestion that the feature is no longer used or the feature is likely to be removed in the future. 

@param tag for every parameter of the method and @throws for many types of exceptions can be included if we want to include all of them in the document.
@return for every nonvoid method/function. We can have only one.
@since version- This is an undocumented tag used to specify when the class method or field that follows. It should be followed by a version number.
The tags may not follow a particular order but it is always good to have a sequence followed as a style approved by the designer.
Embedded HTML
In addition to the normal text, the JavaDoc comment may contain special codes(HTML markup commands).JavaDoc passes HTML commands through to the generated HTML document. This will allow us to format the code and attach it to the webpage.

/**
*System.out.println("Hello Java");
*/

We can use HTML just as we do for other HTML web documents. JavaDoc removes the star or asterisk(*) at the beginning of a line and the white spaces. It reformats everything.It is advisable not to use <hi> or <hr> as embedded since JavaDoc inserts its own heading.
All types of comment documentation :class,variable,method can support embedded HTML.

/**
* even we can use <em>hello</em> a list
*<ol>
*<li>one</li>
*<li>two</li>
*<li>three</li>
*</ol>
*/

Coding guidelines:
Unofficially all class names should start with Capital letters, everything else methods, variables object handles should start with a small letter.
Only constants will contain all capital letters.
An Example


//:Myclass.java (it acts as a marker for comment line containing the source file name
import java.util.*;
/* the first example of java doc
*  @author-Animesh Chatterjee
*  @author-mydigitalvoice.in
*  @version 1.0
*/
public class MyClass{
/** the sole entry point to this class and application 
* @param args Array of String argument
* @return no return value
* @exception no exception is thrown
*/
public static void main(String args[])
{
System.out.println("Hello Java");
}
}
///:~ indicating the end of the source code
 

commands
javac MyClass.java
JavaDoc MyClass.java-author -version[flags]

READ  Class ThreadGroup in Java

Javadoc comments are good practice even if we are not generating the JavaDoc. It is always good to have proper documentation. The best part of JavaDoc is as follows:

  1. The only person who has to look at the piece of java code is the programmer who writes the code. Other people who use the code can find out what the code does by viewing the automatically generated webpage.
  2. Because other people don’t look at the java code, other people don’t make changes to the java code. So they don’t introduce errors into existing code. Errors may be accidental.
  3. Because the client of the code doesn’t look at the java code, they don’t have to decipher the inner working of the java code. All that the client needs to know about the code is what they read in the code’s webpage.
  4. The programmer does not create two different things here(coding and documentation). Instead, the coder creates one piece of java code and attach the documentation inside the code in the form of JavaDoc comments.
  5. The generation of webpages from Javadoc comments is done automatically. So everyone’s documentation has the same format.

Switches of JavaDoc

-author path

Specifies that author information specified with the @author tag in the output.This information is not output by default.

-classpath path

This option specifies a path that JavaDoc uses to look up both class files and source files for the specified package. If we specify this option to tell JavaDoc to look for our source files, we must also be sure to include the standard system classpath as well, or JavaDoc will not be able to find the classes it needs. This option overrides the default path and any path specified by the CLASSPATH environment variable. The path specified is an ordered list of directories and ZIP files, separated
by colons on UNIX systems or semicolons on Windows systems. To specify additional directories or ZIP files to search without overriding the default system classpath, use the CLASSPATH environment variable.

-d directory

The directory in which JavaDoc should store the HTML files it generates. The default is the current directory.

-docencoding encoding-name

Specifies the character encoding to be used for the output documents generated by JavaDoc.

-encoding encoding-name

Specifies the character encoding to be used to read the input source files and the documentation comments they contain.

-Jjavaoption

Pass the argument java option directly through to the Java interpreter. java option should not contain spaces if multiple arguments must be passed to the interpreter, use multiple -OptionsJoptions.

-nodeprecated

Specifies that JavaDoc should not include @deprecated tags in its output, as it does by default.

-noindex

Specifies that java does should not generate the AllNames.html index file that it creates by default.

-notree

Specifies that JavaDoc should not generate the tree.html class hierarchy file that it creates by default.

-sourcepath path

A synonym for -classpath. Note that any specified “sourcepath” must include the system classpath.

-verbose

Tells JavaDoc to print additional messages about what it is doing.

-version path

Specifies that version information specified with the @version tag should be output. This information is not output by default. This option does not tell JavaDoc to print its version number.
Environment CLASSPATH
Specifies an ordered list (colon-separated on UNIX, semicolon-separated on Windows systems) of directories and ZIP files in which JavaDoc should look for the class definitions. When a path is specified with this environment variable, JavaDoc always implicitly appends the location of the system classes to the end of the path. If this environment variable is not specified, then the default path is the current directory and the system classes. This variable is overridden by the -classpath option

READ  Class Random in Java

Note: when JavaDoc cannot find a specified package, it produces a stud HIML file and does not warn you that the package was not found.

LEAVE A REPLY

Please enter your comment!
Please enter your name here