自动注释工具

另请参见

通过使用 IDE 的自动注释工具,您可以确定源代码的 Javadoc 注释是否有效,并且可以根据需要编辑、甚至创建注释。左窗格列出了包含 Javadoc 注释的源代码实体,而右窗格显示了标记和注释本身。

可以使用以下方法打开自动注释工具:在“项目”窗口或源代码编辑器中右键单击要描述的文件,然后从上下文菜单中选择“工具”>“自动注释”。

过滤器工具栏

通过使用过滤器工具栏,可以控制要在自动注释工具中显示的类和成员。下表描述了工具栏中的按钮。

工具栏
按钮
描述
正确图标 显示切换到具有完整 Javadoc 注释的类和成员
错误图标 显示切换到具有不完整或不正确的 Javadoc 注释的类和成员
缺少图标 显示切换到没有 Javadoc 注释的类和成员
公共图标 显示切换到公共方法
包图标 显示切换到使用缺省访问设置的方法
受保护图标 显示切换到使用受保护访问设置的方法
私有图标 显示切换到私有方法

命令按钮

如果实体缺少 Javadoc 注释或具有不正确的 Javadoc 注释,则可以单击命令按钮编辑该命令。下表列出了命令按钮。

如果实体缺少 Javadoc 注释或具有不正确的 Javadoc 注释,则可以单击命令按钮编辑该命令。下面的列表描述了这些命令按钮。

Javadoc 注释文本

可以在自动注释工具的“Javadoc 注释文本”窗格中创建或编辑 Javadoc 注释的文本。注释的第一句应为声明的实体的摘要描述。文本可包括设置描述格式的 HTML 元素(如 <B><I>)。标题元素(如 <H1><H2>)被保留以供 Javadoc 工具使用。可以使用窗口底部的命令按钮将 HTML 元素 <B><I><U><CODE><PRE> 以及 Javadoc {@link} 添加到描述中。例如:

/**
* Returns the Class of this <I>Object</I>. 
* Java has a runtime representation for 
* classes--a descriptor of type Class-- 
* which the method getClass() returns for 
* any Object.
*/

不需要在“Javadoc 注释文本”字段中键入字符 /***/ 或前导星号。当 IDE 将注释添加到源代码时,会自动包含这些字符。

标记

可以在自动注释工具的“标记”窗格中创建或编辑 Javadoc 注释的标记。Javadoc 标记以字符 @ 开头,后接具体的关键字。标记区分大小写。通过使用 Javadoc 标记可以自动为 API 文档生成信息。例如,@author name 将具有指定名称的作者条目添加到生成的文档中。标记必须出现在行首,否则将作为普通文本进行处理。按约定,同名的标记将划分到同一个组中。以下注释包括四个 Javadoc 标记:

/**
* A class representing a screen window.
* For example:
*    Window win = new Window(parent);
*    win.show();
*
* @author  Haley J. Ryan
* @version 1.3 00/08/08
* @see     java.awt.BaseWindow
* @see     java.awt.Button */

要将 Javadoc 标记添加到注释中,请单击“新建”,选择 Javadoc 标记或键入一个新标记,然后单击“确定”。将在“标记”窗格中添加该标记。在“说明”字段中,键入标记的文本。文本可包括 HTML 元素(如 <B><I>)以及内联 Javadoc 标记 {@link}

另请参见
在源代码中输入 Javadoc 注释

法律声明