Get to know coding rule of Javadoc in 10 mins

Contents

1 Javadoc – Java document comment
2 HTML TAG
3 TAG
4 Generating javadoc
5 At the end..
6 Reference (Japanese)

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

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.

@param parameter-name description

@return

Show description of return value.

@return description

@link

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.

Example

    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.

@linkplain

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

@see

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"