Java学习之路[1.1]: Java嵌入式文档工具(javadoc)用法

Javadoc简介:

以下摘自维基百科:https://en.wikipedia.org/wiki/Javadoc

Javadoc（原始为JavaDoc）是由Sun Microsystems为Java语言（现为Oracle Corporation拥有）创建的文档生成器,用于从Java源代码生成HTML格式的API文档.

Javadoc使用的“doc comments”格式是记录Java类的事实上的行业标准.一些IDE,IntelliJ IDEA，NetBeans的和Eclipse等,自动生成Javadoc HTML。许多文件编辑器协助用户生成Javadoc源代码，并将Javadoc信息用作程序员的内部参考。

Javadoc还提供了一个用于创建doclet和taglet 的API ，它允许用户分析Java应用程序的结构。这就是JDiff如何生成关于两个API版本之间变化的报告。

Javadoc不会影响Java中的性能，因为在编译时删除所有注释。编写评论和Javadoc是为了更好地理解代码，从而更好地维护它。

Javadoc风格注释:

以下整理自维基百科:https://en.wikipedia.org/wiki/Javadoc

• 文档注释的基本结构是将它们嵌入其中/** ... */

/**...像这样
*/

• 比一般注释/*...*/在左面多了个星号

代码版本 & 作者信息:

• 注意: 任何import语句都必须在类声明之前
  
  • 一个有效的模板如下:

//导入语句

/ ** 
* @作者名字<邮箱> 
* @version x.x  （当前版本号）
* @Since x.x    （从哪个版本添加到）
* / 
public class Main { 
    / / write code in here
}

方法注释:

• 所有Javadoc都被视为HTML,可以用“ <p>”标记分隔相应段落,解决多段描述。

• 对于方法(下面#数字实际代码中不存在,仅标注):

  • #1 简短的一行描述来解释项目的功能.
    
    • 范围:注释第一行最后一个点号“.”之前的
  • #2 可能跨越多个段落的较长描述,细节可以在这里完整解释。
  • #3 标签部分列出方法的接受输入参数和返回值。

/**
 * #1 简短的一行描述.                         
 * <p>
 * #2 详细描述(可选)
 * <p>
 * #3 更多的解释,在这里,会在Html中段落分割
 * ...
 *  ...
 * @param  变量描述           相应描述
 * @return 返回值描述(可选)    相应描述
 */
public int Method (...) {
    //这个 有返回值
}

• 常用标记以@开头。

  • 包括：
  • @author
    
    • 标明开发该类模块的作者
    • (可多次使用:按时间顺序排列，并用逗号分隔)
  • @version
    
    • 标明该类模块的版本
  • @see
    
    • 参考转向，也就是相关主题
    • (可多次使用:标签遵循由近到远，参数由少到多，由上到下的顺序)
  • @param
    
    • 对方法中某参数的说明
    • (可多次使用:匹配参数列表.)
  • @return
    
    • 对方法返回值的说明
  • @exception
  • @throw
    
    • 对方法可能抛出的异常进行说明
    • (可多次使用:按字母顺序列出的例外的名字)

变量注释:

• 对于变量:

/ ** 
*在这里描述变量。
* / 
private  int  i  =  0 ;

• 可以像这样的(但应避免),可以这样做:

/ ** 
*位置X和Y的坐标
* / 
public  int  positionX , positionY ;       //避免

一个例子:

摘自维基百科:https://en.wikipedia.org/wiki/Javadoc

public class Main {
    /**
     * Validates a chess move.
     *
     * Use {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} to move a piece.
     *
     * @param theFromFile file from which a piece is being moved
     * @param theFromRank rank from which a piece is being moved
     * @param theToFile   file to which a piece is being moved
     * @param theToRank   rank to which a piece is being moved
     * @return            true if the move is valid, otherwise false
     * @since             1.0
     */
    boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
        // ...body
    }

    /**
     * Moves a chess piece.
     *
     * @see java.math.RoundingMode
     */
    private void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)  {
        // ...body
    }
    public static void main(String... args){
        System.out.print("add");
    }
}

Javadoc详细标签列表:

标签和参数	用法	适用于
@ author	描述作者。	类，接口，枚举
{ @docRoot }	表示从任何生成的页面生成的文档根目录的相对路径。	类，接口，枚举，块，方法
@version 版本	提供软件版本输入。每个类或接口最多一个。	类，接口，枚举
@ since 版本	介绍此功能何时首先存在。	类，接口，枚举，块，方法
@see 参考	提供指向其他文档元素的链接。	类，接口，枚举，块，方法
@param 参数	描述一个方法参数。	方法
@return 描述	描述返回值。	方法
@exception **classname description @throws **classname description	描述可能从此方法抛出的异常。	方法
@deprecated 描述	介绍一种过时的方法。	类，接口，枚举，块，方法
{ @inheritDoc }	从重写的方法复制描述。	重写方法
{ @link 参考 }	链接到其他符号。	类，接口，枚举，块，方法
{ @linkplain 参考 }	与{@link}相同，除了链接的标签以纯文本显示而不是代码字体。	类，接口，枚举，块，方法
{ @value #STATIC_FIELD }	返回静态块的值。	静态块
{@ *code ***literal }	格式化代码字体中的文本文本。它相当于 {@ literal} 。	类，接口，枚举，块，方法
{ *@literal ***literal }	表示文字文字。附上的文本被解释为不包含HTML标记或嵌套的javadoc标记。	类，接口，枚举，块，方法
{ *@serial ***literal }	用于默认序列化块的文档注释中。	块
{ @serialData 文字 }	记录由writeObject（）或writeExternal（）方法写入的数据。	块，方法
{ @serialField 文字 }	记录一个ObjectStreamField组件。	块

使用IDE生成Javadoc

IDEA:

• 就拿维基百科上的这个示例演示吧!

public class Main {
    /**
     * Validates a chess move.
     *
     * Use {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} to move a piece.
     *
     * @param theFromFile file from which a piece is being moved
     * @param theFromRank rank from which a piece is being moved
     * @param theToFile   file to which a piece is being moved
     * @param theToRank   rank to which a piece is being moved
     * @return            true if the move is valid, otherwise false
     * @since             1.0
     */
    boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
        // ...body
    }

    /**
     * Moves a chess piece.
     *
     * @see java.math.RoundingMode
     */
    private void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)  {
        // ...body
    }
    public static void main(String... args){
        System.out.print("add");
    }
}

• 我们新建一个Project后把上面代码复制过去:

• 我们根据图片操作:
  

• 相关命令(Other command line arguments ):
  -encoding utf-8 -charset utf-8

• 最后大功告成了!