Java Documentation-JavaDoc Concept Simplified in Java



To use API effectively,we need good documentations.  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 details without going through the code. Static documentation faces challenges of maintenance. If we change the code in,general 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 comment and put them in a useful form.

In java, the tool that extract comments is called javadoc. The documentation for most java APIs are prepared using javadoc. It extracts the comments,class,method names etc from the source file itself.The output of the javadoc is a HTML file which can be seen in a web browser. This tool allows us to create and maintain single source file and generates the documentation automatically.So javadoc is a tool that reads source code file, extracts javadoc comments and create a set of webpages containing comments in a nicely formatted and interlinked form.Javadoc takes the syntactic information to add semantics and pragmatics.

By default javadoc will only collect information about public classes,public subroutines and public members variables,but it also allows 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 sunroutine for which we are commenting on.All the javadoc commands starts with /** and ends with */. There are two ways to create javadoc. They are as follows:

  • Use doc tags 
  • Embedded HTML
Doctags:

Doctags are passed to javadoc tool.Doctags 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 are associated with it.The first sentence of a doc comment should be a summary sentence ,suitable for display. The next few line of sentences may document the feature in details.The text that follows a tag may span multi lines and contimue 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 off several lines. The description ends at the next tag or at the end of comment.

Comments are special section of the text inside a program.It's purpose is to help people understand the program.A comment is part of a 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 allows us to refer to the documentation in other classes. javadoc will generate HTML having a @see tags hyperlinked to  other documentation.@see -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 @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 specially in the generated HTML).It is mostly applicable for 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 specially 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 reference.@see -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 tags 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 is the documentationHere 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 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 which 
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 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 non void 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 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 them to webpage.

/**
*<pre>
*System.out.println("Hello Java");
*</pre>
*/
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 re formats 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 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]

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 are 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 don't look at the java code,they don't have to decipher the inner working of the java code.All what 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 create 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.  

Java Documentation-JavaDoc Concept Simplified in Java Java Documentation-JavaDoc Concept Simplified in Java Reviewed by Animesh Chatterjee on November 19, 2018 Rating: 5

No comments:

Powered by Blogger.