eclipse 注释

来源：互联网发布：德阳cnc编程招聘信息编辑：程序博客网时间：2024/04/30 07:01

JDK包含一个很用的工具，javaDoc,它可以由源文件生成一个HTML文档。

javadoc实用程序从下面几个特性中抽取信息：

1、包；

2、共有类与接口；

3、共有的和受保护的方法；

4、共有的和受保护的域。

注释应该放置在所描述特性的前面。注释如下：

/** * @author Administrator * */

注释在标记之后紧跟着自由格式文本。

自由格式文本：

第一句应该是 概要性 的句子，javadoc实用程序自动地将这些句子抽取出来形成概要页；

自由格式文本中，可以使用HTML修饰符（不可使用<h1>或<hr>，他们会对文档的格式产生冲突），例如：

用于强调的： <em>...<em>；

用于设置等宽“打字机”字体的<code>...</code>；

用于着重强调的 <strong>...</strong>；

包含图像的<img ...>

注释

（<img ...> 使用：应该将注释中使用到的文件统一放到子目录中，如子目录为：doc_img，图片标签应该如此：<img src="doc_img/uml.png" alt="UML diagram">）

个别标记说明：

/** * <!--一句话--><br> * <!--详细<!--<br> * <!--特殊说明、注意事项<!--<br> * @author chenpeibin * @date 2014-6-8 * @version soft0.1.x * @since soft0.1 * @see <!-- 关联部分 --> * <!--@deprecated  取代建议 --> */

@version text :

text 可以是对当前版本的任何描述；

@since text:

text可以是对引入特性的版本描述；

@deprecated text:

此将对类，方法或变量添加一个不再使用的注释，text给出取代的建议。例如：

/** * ... * @deprecated Use <code>setVisible(true)</code> instead */@Deprecatedpublic String getJl(){return jl;}

效果截图：

通过使用@see和@link标记，可以使用超级链接，链接到javadoc文档的相关部分或外部文档。

@see reference:

这个标记将在“see also”部分添加一个超级链接。可以用于类中，也可以用于方法中。

reference 可以是一下的情形之一：

1、package.class#feature label;

2、<ahref="...">label</a>

3、"text"

对于1，可以省略包名，甚至把包名和类名都省去，此时，链接将定位于当前包或当前类，需要注意，一定要使用“#”，而不是使用“.”分隔类名与方法名，或类名与变量名。

对于2，如果@see后面有一个 < 字符，可以超链接到任何URL，还可以指定一个可选的标签作为锚链接，如果省略了label,用户看到的锚的名称就是目标代码名或URL。

对于3，如果@see标记后面有一个“ 字符，文本就是显示在“see also”部分。

可以为一个特性添加多个@see标记，但必须将他们放在一起。

@link :

可以在注释中的任何位置放置指向其他类或者方法的超级链接，以及插入一个专用的标记，特性描述规则与@see标记规则一样，例如：

{@link package.class#featrue label}

包与概述注释

要产生包注释，就需要在每个包目录中添加一个单独的文件。可以有如下两个选择：

1、提供一个以package.html命名的HTML文件。在标记<BODY>... </BODY> 之间的所有文本都会被抽取出来。

2、提供一个以package-info.java命名的JAVA文件。这个文件必须包含一个初始的以/**和*/界定的javadoc注释，跟随在一个包语句之后。它不应该包含更多的代码或注释。

还可以为所有的源文件提供一个概率性的注释。这个注释将被放置在一个名为overview.html的文件中，这个文件位于包含所有源文件的父目录中。标记<BODY>.. </BODY>之间的所有文本将抽取出来。当用户从导航栏中选择“Overview”时，就会显示出这些注释内容。

0 0