Java-文档注释

1 Java注释概述

Java的三种注释：
（1）单行注释：// 注释内容
（2）多行注释：/… 注释内容…./
（3）文档注释：/*.. 注释内容…./
（这种注释可以用来自动地生成文档。在JDK中有个javadoc的工具，可以由源文件生成一个HTML文档。使用这种方式注释源文件的内容，显得很专业，并且可以随着源文件的保存而保存起来。也就是说，当修改源文件时，也可能对这个源代码的需求等一些注释性的文字进行修改，那么，这时候可以将源代码和文档一同保存，而不用再另外创建一个文档。）

文档注释位置：

（1）类注释。类注释用于说明整个类的功能、特性等，它应该放在所有的“import”语句之后，在class定义之前。这个规则也适用于接口（interface）注释。

（2）方法注释。方法注释用来说明方法的定义，比如，方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。

（3）属性注释。默认情况下，javadoc只对公有（public）属性和受保护属性（protected）产生文档——通常是静态常量。

（4）包注释。类、方法、属性的注释都直接放到Java的源文件中，而对于包的注释，无法放到Java文件中去，只能通过在包对应的目录中添加一个package.html的文件来达到这个目的。当生成HTML文件时，package.html文件的和部分的内容将会被提取出来当做包的说明。关于包注释，后面还会有更进一步的解释。

（5）概要注释。除了包注释外，还有一种类型的文档无法从Java源文件中提取，就是对所有类文件提供概要说明的文件。同样的，也可以为这类注释单独新建一个HTML文件，这个文件的名字为“overview.html”，它的和标记之间的内容都会被提取。

·@author：作者。
·@version：版本。
·@docroot：表示产生文档的根路径。
·@deprecated：不推荐使用的方法。
·@param：方法的参数类型。
·@return：方法的返回类型。
·@see：用于指定参考的内容。
·@exception：抛出的异常。
·@throws：抛出的异常，和exception同义

Java除了提供基本的代码注释以外，还提供一种功能更加强大的注释形式：文档注释。如果编写java源代码时添加了合适的文档注释，然后通过JDK提供的Javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。

2、文档注释的作用

当开发一个大型软件时，需要定义成千上万个类，而且需要很多人参与开发。每个人都会开发一些类，并在类里定义一些方法和域提供给其他人使用，但其他人怎么知道如何使用这些类和方法呢？

这时就需要提供一份说明文档，用于说明每个类、每个方法的用途。当其他人使用一个类或者一个方法时，他无需关心这个类或这个方法的具体实现，他只要知道这个类或这个方法的功能即可，然后使用这个类或方法来实现具体的目的，也就是通过调用应用程序接口（API）来编程。

API文档就是用来说明这些应用程序接口的文档。对于java语言而言，API文档通常详细的说明了每个类、每个方法的功能及用法。

3、官方API说明文档效果展示

4、生成自己的API文档

4.1、使用javadoc命令生成文档

4.2、在Eclipse中生成API文档

在eclipse中选择Project–>Generate Javadoc–>选择你想要生成doc的项目工程和文档保存的路径，设置结束后，点击Finish（也可以在next中继续设置一些选项，如文档的标题等）。

这两种方法都可以很快速的帮助我们生成API文档，不过使用命令的时候，经常会遇到编码方面的错误。

eclipse已经帮助我们完成了大量的工作，可以很方便的促进我们的开发。关于API文档这一块儿，如果想要写出高质量的文档，还是应该去参考官方的API文档格式。

---