015_JAVA基础语法_JavaDoc文档

一、什么是JavaDoc

1. JavaDoc，从程序源代码中抽取类、方法、成员等注释形成一个和源代码代码配套的API帮助文档。

2. JavaDoc命令是用来生成自己API文档的。

3. 通俗来讲，只要你在java源码中按一定格式写注释，就可以利用javadoc这款工具自动生成配套的API文档。

二、JavaDoc注释分类

1. JavaDoc注释根据写法和位置不同。主要分为：

   • 写在类/方法上面的javadoc注释。写在类和方法上面的javadoc注释位置不同，但写法相同。

     • 用于描述该类或方法的作用；

     • 此种注释按顺序分为概要描述、详细描述、文档标记三段；

     • 概要描述：

       • 简要描述作用，以英文句号结束，这局话会被提取并放到索引目录中；

       • 当识别到第一个英文句号时，会自动认为概要描述已经结束，紧跟以后的话不会被放到概要描述中；为避免这种情况，可以在英文句号后加上&nbsp，系统会判断&nbsp后的下一个英文句号为概要描述结束的标志。

     • 详细描述

       • 详细描述作用，每段话都以英文句号结束

       • 详细描述中可以使用html标签，如<P>,<a>,<li>等。

     • 文档标记，类似于小标签一样的声明。描述部分和文档标记之间必须空一行。

   • 写在字段上面的javadoc注释

     • 只有public的字段才需要注释，通常是static的。

       /**
       *the static field a
       */
       publicstatic int a = 1；

   • 写在包上面的javadoc注释

     • 格式和写在类/方法上面的javadoc注释一样。

     • 介绍这个包是干嘛的，包的结构，在使用方面的注意事项等信息。

     • 包注释是写在package-info.java文件中的，这个文件在创建包时会自动顺带生成。

2. 注意事项

   • 所有的javadoc注释都以/**开头，*/结尾。

   • 每种javadoc注释都要和其后面对应的类/方法/字段/包 保持同样的缩进

     //错误javadoc注释
     class Student{
     /**
     *没有和下面的方法保持同样的缩进，是错误的写法。
     */
         public int add(int num1,int num2){
             ...
         }
     }

三、如何生产JavaDoc文档

1. 使用dos命令窗口生成

   • 在dos命令窗口（win+R，输入cmd），在目标文件所在目录输入javadoc+（-encoding UTF-8 -charset UTF-8）文件名.java

   • -encoding UTF-8 -charset UTF-8是为了让中文更好的显示。

2. 使用IDEA生产javadoc文档

   • 1.【Tools→Generate JavaDoc】

     

   • 2.按照红色标号即可生产javadoc文档

     

     • Generate JAVaDoc Scope:选择要生成javaDoc文档的文件：整个项目、当前java文件、自选

     • Output directory：java文档生成路径，建议新建一个文件夹用于存储javadoc文档。路径要是用英文路径

     • Locale：文档的提示信息 建议填zh_CN ;zh_CN 代表中文

     • Other command line arguments：编码、title等传递给javadoc的参数。一般这样写：-encoding UTF-8 -charset UTF-8 -windowtitle “文档HTML页面标签的标题” -link http://docs.Oracle.com/javase/7/docs/api

     • 橙色框中代表对哪些生成文档，默认是只对public和protected生成文档。将其向上或向下滑动可改变

     • 其余的就先不了解。

   • 3.结果

     • 找到生成的html

       

     • 

   • 也可以直接打开index.html