Get to know coding rule of Javadoc in 10 mins

Javadoc – Java document comment

Javadoc is used in Java language to write comment with the format stats from “/**” (2 asterisk needed) and ends with “*/” 

 It is used as a explanation document for the program which is embedded in source code. Usually, Brief explanation of Class, method, and member can be written as Javadoc format.

If the Javadoc was written, we can also auto generate HTML type documentation file, for example see Java Platform SE API reference page.  

HTML TAG

HTML tag can be used to write Javadoc, which makes it formatted document and easy to refer. When you use IDE like Eclipse or Android studio, explanation is automatically formatted.

TAG

Nice summary for Javadoc Tag here (English).

Tag Description
@author Author of Class
@param Explanation of method parameter/argument
@return Explanation of method return value
@throw Exception class generated by this method
@see Reference of other API
@deprecated To notify it is not recommended to use
@since Version where this class/method is introduced
@version Version
{@link}

Refer to other class/method

{@linkplain}

Refer to other class/method

 

  • Block tag: @tag 
    Usually the scopr of this tag is until the end of line.
  • Inline tag: {@tag}
    The scope of this tag is inside {}

Usage of major tag

@param

Show description of parameter, member.

@return

Show description of return value.

 

@link

It acts similar to <a href=””> tag of HTML, so that you can embed link to the string.

label” will appear as text, and it has link to “package.class#member“. When the label is omitted, the class/member/method name will be shown. 

Example

See “Javadoc coding rule of  @link, @linkplain, @see” for more details of how to write link.

@linkplain

Same with {@link}, except that the reference string will be shown plaintext instead of code text

@see

Refers other field, method.

or

See “Javadoc coding rule of  @link, @linkplain, @see” for more details of how to write link.

Generating javadoc

javadoc command can be used. It is in the same folder with javac command (java compiler).

Example

You can also refer “javadoc -help”.

At the end..

I read the story that some company decide to hire the engineer after reading his source code with the reason that his documentation comment was really organized. Yes, nice documentation can be a reason to evaluate this engineer has a skill, worth to work together. So it is a nice practice to write documentation comment even for the personal project.

 

Reference (Japanese)

 

Sponsored Links

Leave a Reply

Your email address will not be published.