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,可以用“

    ”标记分隔相应段落,解决多段描述。

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

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

* #2 详细描述(可选) *

* #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后把上面代码复制过去:

Java学习之路[1.1]: Java嵌入式文档工具(javadoc)用法_第1张图片

  • 我们根据图片操作:
    Java学习之路[1.1]: Java嵌入式文档工具(javadoc)用法_第2张图片

Java学习之路[1.1]: Java嵌入式文档工具(javadoc)用法_第3张图片

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

  • 最后大功告成了!

Java学习之路[1.1]: Java嵌入式文档工具(javadoc)用法_第4张图片

你可能感兴趣的:(个人笔记,编程语言∷Java)