通过使用 IDE 的自动注释工具,您可以确定源代码的 Javadoc 注释是否有效,并且可以根据需要编辑、甚至创建注释。左窗格列出了包含 Javadoc 注释的源代码实体,而右窗格显示了标记和注释本身。
可以使用以下方法打开自动注释工具:在“项目”窗口或源代码编辑器中右键单击要描述的文件,然后从上下文菜单中选择“工具”>“自动注释”。
通过使用过滤器工具栏,可以控制要在自动注释工具中显示的类和成员。下表描述了工具栏中的按钮。
工具栏 按钮 |
描述 |
---|---|
![]() |
显示切换到具有完整 Javadoc 注释的类和成员 |
![]() |
显示切换到具有不完整或不正确的 Javadoc 注释的类和成员 |
![]() |
显示切换到没有 Javadoc 注释的类和成员 |
![]() |
显示切换到公共方法 |
![]() |
显示切换到使用缺省访问设置的方法 |
![]() |
显示切换到使用受保护访问设置的方法 |
![]() |
显示切换到私有方法 |
如果实体缺少 Javadoc 注释或具有不正确的 Javadoc 注释,则可以单击命令按钮编辑该命令。下表列出了命令按钮。
如果实体缺少 Javadoc 注释或具有不正确的 Javadoc 注释,则可以单击命令按钮编辑该命令。下面的列表描述了这些命令按钮。
public String myMethod(Object param1, Object param2){}并且您单击了“自动校正”,则在 Javadoc 窗口的“标记”窗格和源代码编辑器中生成以下标记:
@param param1 @param param2 @return
可以在自动注释工具的“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}。