javadoc注释文档小结

javadoc介绍

  Java为了达到将代码同文档链接起方便维护的问题，用javadoc来提取注释来转化为有用的形式的方法来标记文档

  有了javadoc不仅有了创建文档简明直观的标准，并且要求了所有的Java类库也要遵循这种注释语法

  javadoc输出的是一个HTML文件，通过Web浏览器来查看

  我们只需要创建和维护单一的源文件，就可以自动生成有用的文档

  所以在写类注释、阅读和维护文档时，javadoc是必须要了解的，接下来是我自己学习过程时候的总结

  全文阅读和理解过程大概十分钟左右，希望不会浪费读者宝贵的时间

---

javadoc语法

  所有的javadoc命令都必须在“/**”为开始和“*/”为结束的注释中出现

  共有三种类型的注释文档
        类注释：位于类定义之前
        域注释：位于域定义之前
        方法注释：位于方法定义之前

  如下代码简单的例子展示

/**A class comment*/
public class Documentation{
      /**A field comment*/
      public int i;
      /**A method comment*/
      public void f(){}
}

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

  因为程序员期望只有public和protected成员才能在文件之外被引用

---

一些标签实例

• @see：引用其他类

  @see标签允许用户引用其他类的文档
  这样会在每种格式的生成文档中加入一个具有超链接的“See Also”条目
  但是javadoc不会检查你所提供的超链接是否有效
  

• @link package.class#member laber

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

• @docRoot

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

• @inheritDoc

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

• @version

  该标签可以声明任何你认为合适包含在版本说明中的重要问题
  

• @author

  该标签可以说明你的姓名、电子邮件或者其他任何适宜的信息
  

• @since

  该标签允许你指定程序代码最早使用的版本
  多用于指定所用的JDK版本的情况
  

• @param

  该标签作为方法参数列表的标识，可以使用任意多个这种标签
  

• @return

  该标签用于描述返回值的含义
  

• @throws

  该标签对由于某个方法调用失败而抛出的对象的说明
  

• @deprecated

  该标签用于指出一些旧特性已由改进的新特性所替代
  

---

javadoc的生成

  在.java文件路径中执行DOS命令javadoc 文件名.java,回车自动生成注释文档

  生成成功后，点击目录中增加的index.html进入网站进行阅读查看

  养成查看api文档自学的习惯是一名优秀程序员的必修课

  当你在学习和工作中遇到新的类或者方法时，本人推荐在IDE中直接跳转源码的方式直接阅读

  这些就是我自己学习到的javadoc知识，如果存在问题或者有可以完善的地方，希望大佬斧正，希望大家和我一起讨论一起进步