3.1注释

1、Java是强类型语言：所有变量必须先声明后使用，指定类型的变量只能接受类型匹配的值

2、注释看起来是在程序当中是可有可无的一种东西，但是能写出让人一看就懂的注释也是程序员理解力的一种表现。

3、注释分为单行注释，多行注释和文档注释，如果有文档注释，通过JDK的javadoc工具可以直接将源代码中的文档注释提取成为一份系统的API文档，单行注释用//，多行注释用/* */，文档注释用/** */

4、什么事API文档，简单翻译就是借口文档，就是用来说明每个类，每个方法的功能和用法，别人来调用的时候就看看API文档就明白怎么调用你写的类或者方法了，和看说明书一个性质。

5、查看基础类API文档，oracle公司为java中大量的基础类提供相应的API文档，登录官网下载后，在Additional Resources的部分就能找到，小编写文章的时候已经有java 10了，但小编还用的是8，所以下载的是jdk-8u171-docs-all.zip,这个里面包含了API文档也包含了JDK其他说明文档，进行解压后就在docs/api路径下找到index.html文件，进去点击上面一排中的FRAMES进去就是java API首页.

6、特别注意：Java类中只有public或者protected修饰的内容才是会被javadoc处理的，如果开发这希望提取private修饰的内容，在使用javadoc的时候可以添加-private选项

7、在自己开发中，添加文档注释也能利用javadoc工具来生成自己的API文档，用来生成自己代码的说明书。下面就会给大家说怎么搞API说明文档，在此之前先看一组命令

-d<directory>:指定一个路径，用于将生成的API文档放到该目录下

-windowtitle<text>:指定一个字符串，用于设置API文档的浏览器窗口标题

-doctitle:<html-code>:指定一个HTML的文本，用于指定概述页面的标题

-header<text>:指定浏览器左半部分包列表头标题显示

8、首先在自己的某个路径下面创建两个文件夹，一个lee，一个yeeku，在lee文件夹里创建java文件JavadocTest.java，在yeeku文件夹下面创建两个文件JavadocTagTest.java和Test.java，三个.java文件内容如下：

首先是JavadocTest.java

package lee;
/**
*Description:
*网站：<a herf="http://www.crazyit.org">疯狂java联盟</a><br>
*Copyright (c),2001-2005
*Program Name:<br>
*Date:<br>
*@author:taopoppy.github
*@version:1.0
*/

public class JavadocTest
{
  /**
   *简单测试成员变量
   */
  protected String name;

  /**
   *主方法，程序的入口
   */
   public static void main(String[] args)
   {
       System.out.println("Hello World");
    }
}

接着是JavadocTagTest.java

package yeeku;
/**
*Description:
*网站：<a herf="http://www.crazyit.org">疯狂java联盟</a><br>
*Copyright (c),2001-2005
*Program Name:<br>
*Date:<br>
*@author:taopoppy.github
*@version:1.0
*/

public class JavadocTagTest
{
  /**
   *一个得到打招呼字符串的方法
   */
   public String hello(String name)
   {
       return name+"你好！";
    }
}

最后是Test.java

package yeeku;
/**
*Description:
*网站：<a herf="http://www.crazyit.org">疯狂java联盟</a><br>
*Copyright (c),2001-2005
*Program Name:<br>
*Date:<br>
*@author:taopoppy.github
*@version:1.0
*/

public class Test
{
  /**
   *简单测试成员变量
   */
  public int age;

  /**
   *Text类的测试构造器
   */
   public Test()
   {
    }
}

(1)打开命令行进入到我们lee和yeeku文件夹所在路径，进入lee，

输入命令javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 *JavadocTest.java

命令也很好理解，结合前面我们列出的命令解释，就是使用javadoc工具来在当前lee文件夹里面创建一个apidoc文件夹(假如之前没有这个文件夹就会自动创建)，把有关JavadocTest.java源文件中的文档注释提取成API文档放进其中。

（2）进入到apidoc文件夹里，打开index.html就可以看到API文档信息

（3）类似的我们进入到yeeku文件夹中：这里特别注意，由于有两个文件夹，假如我们先后使用下面两个命令

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 *JavadocTagTest.java

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 *Test.java

结果就是在yeeku/apidoc路径下的index.heml浏览器中你只能看到Test.java相关的API文档，因为JavadocTagTest.java相关的API文档被第二个命令覆盖了，正确的做法就是使用下面的命令

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 *.java

*.java表示当前路径下的所有java源文件，这样连个java源文件的相关API文档就都在其中了

（4）当然我们在写文档注释时，文档注释中的@author和@version是不会显示在API文档中的，可以手动在命令中增加 -author 和-version

（5）最后我们来对lee和yeeku两个包生成API文档：进入到包含lee和yeeku的路径下面，输入命令

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 -version -author lee yeeku

在该路径下就生成了关于两个包的API文档

（6）进入到生成的apidoc文件中，打开index.html,如下所示

这下我们的API文档应该是和官方的非常接近了

深入学习Java之二：注释和javadoc工具的使用

3.1注释

猜你喜欢