Java Documentation-JavaDoc Concept Simplified in Java

0
17
Spread the love
  • 1
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
    1
    Share


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 [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 @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 [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 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.

Don't miss out!
Subscribe To Newsletter

Receive top technical news, lesson ideas, travel tips and more!

Invalid email address
Give it a try. You can unsubscribe at any time.

Spread the love
  • 1
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
    1
    Share

LEAVE A REPLY

Please enter your comment!
Please enter your name here