javadoc那些事

1.javadoc是什么？

  javadoc是用于提取注释的工具，是JDK安装的一部分。它采用了Java编译器的某些技术，查找程序内的特殊注释标签。它不仅可以解析标签标记的信息，还将毗邻注释的类名或方法名抽取出来。这样我们就可以用最少的工作量，生成相当好的程序文档。
  javadoc输出的是一个HTML文件。
  了解javadoc，帮助你更好得阅读源码！

2.语法

  所有javadoc命令都只能在/**注释中出现，结束语*/。使用javadoc的方式主要有两种：嵌入HTML，或使用文档标签。

“文档标签”两种类型：

• 独立文档标签
  • 一些以“@”字符开头的命令，且要置于注释行的最前面。
• 行内文档标签
  • 可以出现在javadoc中的任何地方，也是以“@”字符开头，但要在花括号内。

javadoc只能为public和protected成员进行文档注释。

3.嵌入式HTML

HTML标签

代码注释

文档显示

加入简单的样式

代码注释

文档显示

  突然感觉发现新大陆！！！😂😂😂
  有没有感觉很有趣！！！😀😀😀
  更多有趣的事情等着你去发现！

  注意：不要在嵌入式HTML中使用标题标签，例如<h1>或<hr>,因为javadoc会插入自己的标题，而你的标题可能同它们冲突。

4.一些标签示例

4.1. @see：引用其他类

  @see标签允许用户引用其他类的文档。javadoc会在其生成的HTML文件中，通过@see标签链接到其他文档，会在生成的文档中加入一个具有超链接的“See Also”(参见)条目。
例如：
代码注释

文档显示

4.2.{@link package.class#member label}

  该标签与@see及其相似，只是它用于行内，并且是用“label”作为超链接文本，而不是“See Also”。

代码注释

文档显示

4.3.{@docRoot}

  该标签产生到文档根目录的相对路径，用于文档树页面的显示超链接。

4.4.{@inheritDoc}

  该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

4.5.@version

  格式：@version version-infomation
  version-infomation可以是任何你认为适合包含在版本说明中的重要信息。
如果javadoc命令使用了-version标记，那么就从生产的HTML文档中特别提取出版本信息。

4.6.@author

  格式：@author author -information
  author -information中可以是你的姓名，也可以包括电子邮件或者其他任何适宜的信息。
如果javadoc命令行使用了-author标记，那么就从生成的HTML文档中特别提取作者信息。

4.7.@since

  该标签允许你指定程序代码最早使用的版本，可以在HTML Java文档分钟看到它被用来指定所用的JDK版本的情况。

4.8. @param

  格式：@param parameter-name description
  parameter-name是方法的参数列表中的标识符，description是可延续数行的文本，终止于新的文档标签出现之前。

4.9.@return

  格式：@return description
  description用来描述返回值的含义，可以延续数行。

4.10.@throws

  格式：@throws fully-qualified-class-name description
  fully-qualified-class-name给出一个异常类的无歧义的名字，而该异常类在别处定义。
description告诉你为什么此特殊类型的异常会在方法调用中出现。

4.11. @deprecated

  该标签用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，因为在不久的将来它们很可能会被删除。如果使用一个标记为@deprecated的方法，则会引起编译器发布警告。
在Java SE5中，Javadoc标签@deprecated已被@Deprecated注解所替代。