java文档注释规范（一）

时间：2022-09-06 13:21:18

https://blog.csdn.net/huangsiqian/article/details/82725214

Javadoc工具将从四种不同类型的“源”文件生成输出文档：Java语言类的源文件（.java），包注释文件，概述注释文件和其他未处理的文件。

包注释文件（Package Comment File）
每个包都有自己的文档注释。有两种方式来创建包注释文件：

package-info.java - 可以包含包的声明，包注解（anotation），包注释和Javadoc 标签（tag）。包注释放在包声明之前。这是JDK 5.0新引入的特性。如下。

File: java/applet/package-info.java  注意：文档注释块内部行首的*号是可选的

/**

 * Provides the classes necessary to create an applet and the classes an applet uses

 * to communicate with its applet context.

 * <p>

 * The applet framework involves two entities:

 * the applet and the applet context. An applet is an embeddable window (see the

 * {@link java.awt.Panel} class) with a few extra methods that the applet context

 * can use to initialize, start, and stop the applet.

 *

 * @since 1.0

 * @see java.awt

 */

package java.lang.applet;

package.html - 只能包含包注释和Javadoc标签，不能包含包注解。注释包含在<body>元素内部。
注意：只能包含其中一个文件，如果同时包含两个文件，则 package.html 将被忽略。如下。

File: java/applet/package.html

<HTML>

<BODY>

Provides the classes necessary to create an applet and the classes an applet uses

to communicate with its applet context.

<p>

The applet framework involves two entities:

the applet and the applet context. An applet is an embeddable window (see the

{@link java.awt.Panel} class) with a few extra methods that the applet context

can use to initialize, start, and stop the applet.

@since 1.0

@see java.awt

</BODY>

</HTML>

包注释的第一句应该对包进行概括。Javadoc tool 将会将这句话作为summary statement.对于包注释内容的具体书写可以参考：How to Write Doc Comments for Javadoc

javadoc工具将会以如下方式处理包注释文件：

复制注释并进行处理（对于package.html，复制<body>和</ body> HTML标记之间的所有内容）。
处理注释中存在的包标签。
将处理后的文本插入生成的包摘要页面的底部，参见java api 文档格式。
将包注释的第一句复制到包摘要页面的顶部。 并将包名称和第一个句子添加到概述页面上的包列表中。
概述注释文件（Overview Comment File）
Javadoc工具将由它生成概述页面。可以将概述注释文件命名为任何名称（一般命名为overview.html）并放在任何位置（通常放在source tree的顶层）。例如，如果java.applet包的源文件包含在C：\ user \ src \ java \ applet目录中，则可以将概述注释文件创建为C：\ user \ src \ overview.html。

概述注释文件的内容也是HTML编写的大文件注释，类似于包注释文件。注释的第一个句子作为应用程序或包集合的摘要，不要在<body>和第一个句子之间放置标题或任何其他文本。除了内嵌标签（例如{@link}）之外的所有标签必须出现在主要描述之后。如果应用@see标签，则必须用fully-qualified name。

运行Javadoc工具时，使用-overview选项指定概述注释文件名。javadoc工具处理该文件的方式类似于包注释文件的处理。

复制<body>和</ body>标记之间的所有内容并进行处理。
处理注释中存在的概述标签。
将处理后的文本插入生成的概述页面的底部。
将概述注释的第一句复制到概述摘要页面的顶部。
其他未处理的文件（Miscellaneous Unprocessed Files）
可以在源文件中包含任何杂项文件（由Javadoc工具复制到目标目录）。通常包括图像文件，Java示例源代码（.java）和类（.class）文件，独立的HTML文件。
未处理的文件应放在包含源文件的任何包目录下，名为doc-files的目录中。可以包括图像，示例代码，源文件，.class文件，applet和HTML文件。例如，如果要在java.awt.Button类文档中包含按钮button.gif的图像，则将该文件放在/ home / user / src / java / awt / doc-files /目录中。请注意，doc-files目录不应位于/ home / user / src / java / doc-files中，因为java目录不直接包含任何源文件。

这些未处理文件的所有链接都必须是硬编码的，因为Javadoc工具只是将目录及其所有内容复制到目标。例如，Button.java doc注释中的链接可能如下所示

  /**

    *此按钮如下所示：

    * <img src =“doc-files / Button.gif”>

    */

测试文件和模板文件
一些开发人员表示他们希望将源代码树中的测试文件和模板文件存储在相应的源文件附近。也就是说，他们希望将它们放在这些源文件的同一目录或子目录中。
如果通过显式传入单个源文件名来运行Javadoc工具，则可以故意忽略测试和模板文件以防止它们被处理。但是，如果要传递包名称或通配符来运行Javadoc工具，则需要遵循某些规则以确保不处理这些测试文件和模板文件。

测试文件与模板文件的不同之处在于前者是合法的，可编译的源文件，而后者不是，但可能以“.java”结尾。

可以将测试文件放在子目录中（该子目录是一个无效的包名）。例如，如果要在com.package1中为源文件添加测试文件：

com/package1/test-files/
Javadoc工具将跳过测试目录，没有任何警告。
如果您的测试文件包含doc注释，则可以设置单独的Javadoc工具运行，以通过传入带有通配符的测试源文件名来生成测试文件的文档，例如com / package1 / test-files / * .java。

源文件的模板文件的名称通常以“.java”结尾，并且不可编译。如果您有要保留在源目录中的源文件的模板，则可以使用短划线（例如Buffer-Template.java）或任何其他非法Java字符命名，以防止对其进行处理。

Java源文件中的文档注释
注释的位置：文档注释仅紧接放置在类，接口，构造函数，方法或字段声明之前。放置在方法体中的文档注释将被忽略。

文档注释由主要描述部分 + 标签部分组成：主要描述在起始分隔符/ **之后开始，一直到标签部分。 标签部分以第一个块标签开始，块标记由一个@字符定义（忽略前导 *，空格和前导分隔符/ **）。 可以只有标签部分而没有主要描述部分。 标签部分开始后，不能续接主要描述部分。 标签的参数可以跨越多行。 可以有任意数量的标签：某些类型的标签可以重复，而其他标签则不能重复。 例如，这个@see标签部分

/**

 * This sentence would hold the main description for this doc comment.

 * @see java.lang.Object

 */

块标签和内嵌标签。

有两种标签：块标签（显示为@tag（也称为“独立标签”））和内嵌标签（显示在花括号内）为{@tag}。块标签必须出现在行的开头，忽略前导 *，空格和分隔符（/ **）。 这意味着可以在文本的其他位置使用@字符，而不会被解释为标签的开始。 如果要以@字符作为一行的开始（非标签的开始），请使用HTML实体 @。 每个块标签都有关联的文本，包括标签之后的任何文本，直到下一个标签或文档注释的结尾。关联文本可以跨越多行。在允许文本的任何地方允许放置内嵌标签。 以下示例包含块标签@deprecated和内嵌标签{@link}。

/**

* @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}

*/

注释以HTML格式编写：文本必须用HTML编写，应该使用HTML实体并且可以使用HTML标签。 例如，小于（<）和大于（>）符号应该写为＆lt; 和＆gt;。 同样，＆符号应该写成＆amp;  以下示例中显示了粗体HTML标记<b>。

/**

* This is a <b>doc</b> comment.

* @see java.lang.Object

前导 * ：每行上的前导星号（*）字符是可选的。从1.4开始，如果省略行上的前导星号，则不再删除前导空格。这使您可以将代码示例直接粘贴到<PRE>标记内，并且可以遵循其缩进。浏览器通常更加统一地解释空格。注意，缩进是相对于左边距（而不是分隔符/ **或<PRE>标记）。

每个文档注释的第一句应该是一个简短的句子，包含对已声明实体的简明但完整的描述。这句话在第一个句点处结（后面紧跟空格，制表符或行终止符），或者在第一个块标签前结束。 Javadoc工具将第一个句子复制到HTML页面顶部的成员摘要中。

Java允许在单个语句中声明多个字段，但此语句只能有一个文档注释。因此，如果您需要为每个字段添加单独的文档注释，则必须分别声明每个字段。例如，以下文档注释没有意义，应当作为两个字段声明处理：

/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this
在为成员（members）编写文档注释时，最好不要使用HTML标题标签，例如<H1>和<H2>。因为Javadoc工具会创建整个结构化的文档，而这些标题标签可能会影响对生成文件的格式化 。不过，可以在类和包注释中使用这些标题标签。

自动复制方法注释

Javadoc工具能够在以下两种情况下复制或“继承”类和接口中的方法注释。注意：构造函数，字段和嵌套类不继承文档注释。
 当方法注释中缺少一个主要描述或@return，@ param或@throws标签时，Javadoc工具从其所重写或实现的方法中复制相应的主要描述或标签注释（如果有的话）。（复制算法见下述：用于继承方法注释的算法）
更具体地说，当缺少某个特定参数的@param标签时，将从继承层次结构中的方法复制该参数的注释。如果缺少某个特定异常的@throws标签，则仅在该异常已被声明时才复制@throws标签。此行为与1.3版本及更早版本形成相违背（其中，任何主要描述或标签的存在将阻止所有注释被继承）。

显式继承-在方法主要描述或@return，@ param或@throws标签注释中插入内联标记{@inheritDoc} ， 相应的主要描述或标签注释将复制到该方法。被继承的方法所在的源文件只需要在-sourcepath指定的路径上，以便文档注释可用于实际的复制。无论是类还是其包都不需要在命令行中传入。这与1.3.x及更早版本形成相违背（其中类必须是被文档记录的类（documented class））。

从类和接口继承注释有三种可能情况：

当类中的方法重写超类中的方法时
当接口中的方法覆盖超级接口中的方法时
当类中的方法实现接口中的方法时
在前两种情况下，对于方法覆盖，Javadoc工具在重写的方法的文档中生成一个子标题“Overrides”，其中包含指向它所覆盖的方法的链接，无论注释是否被继承。

在第三种情况下，Javadoc工具在重写方法的文档中生成子标题“Specified by”，并带有指向它所实现的方法的链接。无论注释是否被继承。

用于继承方法注释的算法 - 如果方法没有文档注释或者方法的文档注释中有{@inheritDoc}标签，则Javadoc工具使用以下算法搜索最具体适用的注释，该算法优先考虑接口，而不是超类：

按照它们在方法声明中的implements（或extends）后面出现的顺序查看每个直接实现（或扩展）的接口。使用此方法找到的第一个doc注释。
如果步骤1未能找到文档注释，则以与步骤1中检查的顺序相同的顺序递归地将此整个算法应用于每个直接实现（或扩展）的接口。
如果步骤2找不到文档注释，并且这是一个除Object之外的类（不是接口）：1，如果超类具有此方法的doc注释，那么就使用它。2，如果步骤1未能找到doc注释，则递归地将整个算法应用于超类。

java文档注释规范（一）的更多相关文章

  1. java基础课程笔记 static 主函数 静态工具类 classpath java文档注释 静态代码块 对象初始化过程 设计模式 继承 子父类中的函数 继承中的构造函数 对象转型 多态 封装 抽象类 final 接口 包 jar包

    Static那些事儿 Static关键字 被static修饰的变量成为静态变量(类变量) 作用:是一个修饰符,用于修饰成员(成员变量,成员方法) 1.被static修饰后的成员变量只有一份 2.当成员 ...

  2. JAVA 文档注释，类的说明，HTML说明文档的生成

    有的时候,我们会写一些类,编译成.class文件,给别人使用,那么,别人不知道这个类有哪些方法,如何调用. 所以我们需要做一个类的说明文档. 可以采用在.java类里面进行注释,通过注释来生成类的说明 ...

  3. Java - 34 Java 文档注释

    Java 文档注释 Java只是三种注释方式.前两种分别是// 和/* */,第三种被称作说明注释,它以/** 开始,以 */结束. 说明注释允许你在程序中嵌入关于程序的信息.你可以使用javadoc ...

  4. Java-Runoob-高级教程：Java 文档注释

    ylbtech-Java-Runoob-高级教程:Java 文档注释 1.返回顶部 1. Java 文档注释 Java 支持三种注释方式.前两种分别是 // 和 /* */,第三种被称作说明注释,它以 ...

  5. Java 学习（20）：Java Applet 基础 &amp&semi; Java 文档注释

    -- Java Applet 基础 -- Java 文档注释 Java Applet 基础 Applet 是一种 Java 程序.它一般运行在支持 Java 的 Web 浏览器内.因为它有完整的 Ja ...

  6. 如何为我们的程序编写开发文档——Java文档注释

    Java文档注释是用于生成Java API文档的注释,通过在程序中的类.属性.方法部分加上注释,就可以用javadoc命令生成漂亮的API文档,是程序员进阶的必备技能. 注意,文档注释只说明紧跟其后的 ...

  7. Java文档注释全攻略

    注释:注释起到对代码标注和解释的作用,如果你去看看JDK源码,会发现他们有许多的注释,而且注释是比代码还要多的,可见为代码添加注释是非常重要的,写好注释能让别人更加容易看懂你的代码,注释可以分为以下三 ...

  8. java文档注释--javadoc的用法

    1.前言 Java中有三种注释方式.前两种分别是 // 和 /* */,主要用于代码的注释,以此来方便代码的可读性.第三种被称作说明注释或文档注释,它以 /** 开始,以 */结束,文档注释允许你在程 ...

  9. JAVA文档注释标签

    1 常用Java注释标签(Java comment tags) @author  作者 @param  输入参数的名称  说明 @return 输出参数说明 @since JDK版本 @version ...

随机推荐

  1. 内核控制Meta标签：让360浏览器默认使用极速模式打开网页&lpar;转&rpar;

    为了让网站页面不那么臃肿,也懒的理IE了,同时兼顾更多的国内双核浏览器,在网页页头中添加了下面两行Meta控制标签. 1,网页头部加入 <meta name="renderer&quo ...

  2. 基于jquery封装通用的控制显示隐藏的方法

    应用场景 在项目中会存在大量这样的需求: 1.选择不同的radio单选框,页面上的部分内容随之显示隐藏 2.选择不同的option下拉框内容,页面上的部分内容随之显示隐藏 如果每次遇到这类需求都单独写 ...

  3. C&num;（数据类型）

    刚开始学c#!!!

  4. 分页存储过程--From：桌面备份 -&gt&semi; sql2005新功能&period;docx

    二.以下示例将返回行号为 50 到 60(含)的行,并以 OrderDate 排序. USE AdventureWorks; GO WITH OrderedOrders AS (SELECT Sale ...

  5. add-apt-repository cloud-archive&colon;liberty

    apt-get update && apt-get upgrade;

  6. Android NOtification 使用（震动 闪屏 铃声）

    一. Notification 简介 在 android 系统中,在应用程序可能会遇到几种情况需要通知用户,有的需要用户回应,有的则不需要,例如: * 当保存文件等事件完成,应该会出现一个小的消息,以 ...

  7. RESTFul Shiro

    RESTFul与服务没有关系?REST的本质是设计风格,不是技术. REST的URL还是个URL,就是个普通的URL,访问这个URL的时候,先被Servlet Filter(即Shiro 的Filte ...

  8. JavaSE习题 继承接口和泛型

    问答题: 1.子类在什么情况下可以继承父类友好成员? 答:在同一个包内 2.子类通过怎样的方法可以隐藏继承的成员变量? 答:声明一个与父类相同变量名的成员变量 3.子类重写继承的方法原则是什么? 答: ...

  9. PCIe扫盲——一个Memory Read操作的例子

    连载目录篇:http://blog.chinaaet.com/justlxy/p/5100053251 前面的一系列文章简要地介绍了PCIe总线的结构.事务层.数据链路层和物理层.下面我们用一个简单地 ...

  10. FlowPortal-BPM——创建新模块

    一.设置webconfig (1)数据源设置 添加所有所用到数据库 (2)修改企业信息 二.Main.ashx——添加新的功能选项卡 new { id = "EXECUTE", t ...

相关文章