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 “*/” 

//  This is usual one line comment
/*  This is usual multiline comment */

/** Javadoc is written in here */

 * Usually Javadoc is written in multiline
 * with this format. 

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


Nice summary for Javadoc Tag here (English).

@authorAuthor of Class
@paramExplanation of method parameter/argument
@returnExplanation of method return value
@throwException class generated by this method
@seeReference of other API
@deprecatedTo notify it is not recommended to use
@sinceVersion where this class/method is introduced
{@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


Show description of parameter, member.

@param parameter-name description


Show description of return value.

@return description


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

{@link package.class#member label}

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. 


    public class SampleLink{
        String variable;

         * Sets variable
         * Refer {@link SampleLink#getVar() getName} to get variable.
         * @param var variable
        public void setVar(String var){
            variable = var;

         * Gets variable.
         * Refer {@link #setVar(String)} for setting variable.
         * @return variable String
        public String getVar(){
            return variable;

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


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


Refers other field, method.

@see reference


@see package.class#member label

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).

javadoc "scope" -d "destination" -sourcepath "root directory of source" "package name"


javadoc -d doc

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)

Leave a Comment

Your email address will not be published. Required fields are marked *