如果你读过 Java 源码, 那你应该已经见到了源码中优美的 javadoc 在 eclipse 中鼠标指向任何的公有方法都会显示出详细的描述, 例如返回值作用异常类型等等
本文主要来自 Thinking in java 的内容以及我在工作中写 javadoc 的经验
三种类型的注释文档
注释文档有三种类型, 分别对应于注释位置后面的三种元素: 类域和方法也就说类注释正好位于类定义之前; 域注释位于域定义之前; 方法注释位于方法定义之前如图所示:
- //: object/Documentation1.java
- /** 类注释 */
- public class Documentation1 {
- /** 域注释 */
- public int i;
- /** 方法注释 */
- public void f() {}
- } ///:~
注意, javadoc 只能为 public 和 protected 成员进行文档注释 private 和包内可访问成员的注释会被忽略掉, 所以在输出结果中看不到他们如果想在输出结果中查看可以使用 -private 进行标记这样做是因为只有公用的和受保护的成员才能在文件之外被使用上述代码生成的 html 文档可以在浏览器中查看
嵌入式 HTML
javadoc 通过生成的 html 文档传送 HTML 命令, 这使你能充分利用 HTML
- /**
- * <pre>
- * System.out.println(new date())
- * </pre>
- */
- ///:~
从上述注释中我们也能看出, 注释是会进行输出的, 所以才会有
System.out.println(new date())
这个代码
还可以用 HTML 代码格式化注释:
- /**
- * You can <em>even</em> insert a list:
- * <ol>
- * <li> item one
- * <li> item two
- * <li> item three
- * </ol>
- */
- ///:~
注意, 每一行星号以及之后的空格内容不会输出到文档中, 另外也不要在 javadoc 中使用标题标签, 例如
或者
这是因为 javadoc 会插入自己的标题, 而你的标题可能同它们发生冲突
javadoc 标签
1.@see: 引用其他类
**@see** 标签允许用户引用其他类的文档 javadoc 会在其生成的 HTML 文件中, 通过 **@see** 标签链接到其他文档格式如下:
@see 类名
@see 完整类名
@see 完整类名 #方法名
每一格式都会在生成的文档里自动加入一个超链接的 See Also(参见) 条目注意 javadoc 不会检查我们指定的超链接, 不会验证它们是否有效
2.{ @link package.class#member label }
该标签与 @see 极其相似, 只是它用于行内, 并且是用 label 作为超链接文本而不用 See Also
3.{ @docRoot }
该标签产生到文档根目录的相对路径, 用于文档树页面的显示超链接
4.{ @inheritDoc }
该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中
5. @version
格式如下:
@version version-information
其中, version-information 代表任何适合作为版本说明的资料若在 javadoc 命令行使用了 - version 标记, 就会从生成的 HTML 文档里提取出版本信息
6. @author
格式如下:
@author author-information
- /**
- * Compares this string to the specified object. The result is {@code
- * true} if and only if the argument is not {@code null} and is a {@code
- * String} object that represents the same sequence of characters as this
- * object.
- *
- * @param anObject
- * The object to compare this {@code String} against
- *
- * @return {@code true} if the given object represents a {@code String}
- * equivalent to this string, {@code false} otherwise
- *
- * @see #compareTo(String)
- * @see #equalsIgnoreCase(String)
- */
- public boolean equals(Object anObject) {
- if (this == anObject) {
- return true;
- }
- if (anObject instanceof String) {
- String anotherString = (String)anObject;
- int n = value.length;
- if (n == anotherString.value.length) {
- char v1[] = value;
- char v2[] = anotherString.value;
- int i = 0;
- while (n-- != 0) {
- if (v1[i] != v2[i])
- return false;
- i++;
- }
- return true;
- }
- }
- return false;
- }
来源: http://www.bubuko.com/infodetail-2504916.html