javadoc 文档注释

发表于 更新于 分类于 ， ， Waline： 本文字数： 2k 阅读时长 ≈ 2 分钟

文档注释写法

文档注释:/**...*/则是为支持jdk 工具javadoc.exe而特有的注释语句。javadoc 工具能从java 源文件中读取第三种注释， 并能识别注释中用@标识的一些特殊变量,制作成HTML 格式的类说明文档。javadoc不但能对一个 java 源文件生成注释文档，而且能对目录和包生成交叉链接的 html 格式的类说明文档
@author 作者名
@version 版本标识
@parameter 参数名及其意义 @since 最早出现的JDK 版本
@return 返回值
@throws 异常类及抛出条件
@deprecated 引起不推荐使用的警告
@see 交叉参考

api文档生成

javadoc作用命令处理范文

javadoc工具默认只处理以public或 protected修饰的

  1. 类、
  2. 接口、
  3. 方法、
  4. 成员变量、
  5. 构造器，
  6. 内部类之前的文档注释。

其他地方，如方法中,构造函数中,……的文档注释,javadoc工具不会处理。

提取private的内容

如果开发者确实希望 javadoc工具可以提取 private修饰的内容,则可以在使用 javadoc工具时增加 -private选项

javadoc命令格式

javadoc命令的基本用法如下:

1
javadoc 选项 Java源文件|包

javadoc的常用选项有如下几个。

  • -d :该选项指定一个路径,用于将生成的API文档放到指定目录下,如果不指定则放在当前目录下
  • -windowtitle :该选项指定一个字符串,用于设置API文档的浏览器窗口标题。
  • -doctite :该选项指定一个HTML格式的文本,用于指定概述页面的标题。
  • -header :该选项指定一个HTML格式的文本,包含每个页面的页眉。

除此之外, javadoc命令还包含了大量其他选项,读者可以通过在命令行窗口执行 javadoc-help来查看 javadoc命令的所有选项。
javadoc命令可对源文件、包生成API文档,在上面的语法格式中,Java源文件可以支持通配符,例如,使用*.java来代表当前路径下所有的Java源文件。

实例

JavadocTagTest.java:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
package myjavadoc.test;
/**
 * Description:
 * 这是当前类的简介
 * @author Silly blue
 * @version 1.0
 */
public class JavadocTagTest
{
        /**
         * 一个得到打招呼字符串的方法。
         * @param name 该参数指定向谁打招呼。
         * @return 返回打招呼的字符串。
         */
        public String hello(String name)
        {
                return name + "，你好！";
        }
}

Test.java:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
package my.test;

/**
 * Description:
 * 这是一个测试类.
 * 哈哈哈哈哈哈.
 */
public class Test
{
    /**
     * 简单测试成员变量
     */
    public int age;
    /**
     * Test类的测试构造器
     */
    public Test()
    {
    }
}


测试:

1
javadoc -d C:\Users\lan\Desktop\TestJavaDoc -windowtitle 测试windowtitle -doctitle 测试doctile -header 测试header Test.java Javad JavadocTest.java

到路径C:\Users\lan\Desktop\TestJavaDoc下，可以看到有一堆html,css,js等文件：

浏览器打开index.html,这个是我们生成的api的入口,各个选项对应的位置:

不指定-windowtitle，-doctitle，-header的效果如下:

1
javadoc -d C:\Users\lan\Desktop\TestJavaDoc Test.java JavadocTagTest.java

显示效果:

javadoc标记

标记的使用是有位置限制的
可以出现在类或者接口文档注释中的有@see、@deprecated、 @author、 @version等;

序号 英文 读音
1 deprecated
2 author

javadoc标记

@see的运用

see的句法有三种：

参考链接

Javadoc 使用详解