JAVADOC注释详解

本是古典何须时尚 2022-06-12 07:19 273阅读 0赞

### java注释的分类 ###

1、单行注释：int SUM = 100; //这是一个单行注释

2、多行注释：

/\*

\*这是一个多行注释  
     \*/

3、文档注释：

/\*\*

\*这是一个文档注释

\* @return a

\*/

### java注释和文档注释 ###

作为一个java程序员我们一定都喜欢看官方的开发文档，文档中很详细的包括了类和接口参数方法等信息，并提供了许多类之间的关系等等。java的开发文档是由HTML页面进行展示的，但是用了很久我们才知道，这些文档实际上不是一点一点的写出来的，我们自己也可以进行生成。

安装了 JDK 之后，安装目录下有一个 src.jar 文件或者 src.zip 文件，它们都是以 ZIP 格式压缩的，可以使用 WinZip 解压。解压之后，我们就可以看到分目录放的全是 .java 文件。是了，这些就是 Java 运行类的源码了，非常完整，连注释都写得一清二楚，我们可以对比这里的注释和开发文档，以java.util.List为例：这是官网API截图

![Center][]

接下来再看一下源码信息：

package java.util; 
 
/\*\* 
 \* An ordered collection (also known as a sequence).  The user of this 
 \* interface has precise control over where in the list each element is 
 \* inserted.  The user can access elements by their integer index (position in 
 \* the list), and search for elements in the list. 
 \* 
 \* Unlike sets, lists typically allow duplicate elements.  More formally, 
 \* lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt> 
 \* such that <tt>e1.equals(e2)</tt>, and they typically allow multiple 
 \* null elements if they allow null elements at all.  It is not inconceivable 
 \* that someone might wish to implement a list that prohibits duplicates, by 
 \* throwing runtime exceptions when the user attempts to insert them, but we 
 \* expect this usage to be rare. 
 \* 
 \* The <tt>List</tt> interface places additional stipulations, beyond those 
 \* specified in the <tt>Collection</tt> interface, on the contracts of the 
 \* <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and 
 \* <tt>hashCode</tt> methods.  Declarations for other inherited methods are 
 \* also included here for convenience.

.....

\* @param <E> the type of elements in this list 
 \* 
 \* @author  Josh Bloch 
 \* @author  Neal Gafter 
 \* @see Collection 
 \* @see Set 
 \* @see ArrayList 
 \* @see LinkedList 
 \* @see Vector 
 \* @see Arrays\#asList(Object\[\]) 
 \* @see Collections\#nCopies(int, Object) 
 \* @see Collections\#EMPTY\_LIST 
 \* @see AbstractList 
 \* @see AbstractSequentialList 
 \* @since 1.2 
 \*/ 
 
public interface List<E> extends Collection<E> \{

.....

可以看出来，java的开发文档其实就是在将代码中的注释按照相应的规则整理出来的，这对程序的阅读者和使用者十分关键，由此可见，学会写注释对于一个程序员来说是十分关键的，也能体现一个程序员的水平。

### 文档和文档注释的格式 ###

文档注释可以用在类，方法，属性上进行说明。文档内部要注意细节问题。

文档的生成格式是HTML，而HTML中的格式标识符并不是javadoc加的，而是我们在写注释的时候写上去的，比如，需要换行的时候，不是敲入一个换行符，而是写一个 ，如果要分段，需要使用

因此，格式化文档，就是在注释中添加HTML相应的标签。

文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 \* 号及 \* 号以前的空格，再输入到文档的。如：  
/\*\*  
\* This is first line. ＜br＞  
**\*** This is second line. ＜br＞  
This is third line.  
\*/

编译输出后的HTML源码则是：  
This is first line. ＜br＞  
This is second line. ＜br＞  
This is third line.

\*注意，文档说明后面需要紧跟类、接口、方法或属性

### 文档注释的三个组成部分  ###

![Center 1][]   ![Image 1][]

第一个部分作为类、接口、方法、属性的简述。简述在文档注释的最前面，简述的末尾需要加上一个点号“.”，就是使用点号来分割文档注释，有的时候点号会出现错误，我们就用作为第二部分的开头进行分割。

第二部分就是注释的详细部分，对属性或方法等进行详细的说明，在格式上没有什么特殊的要求。

第三部分是特殊说明部分，这个部分包括声明作者、版本说明、参数说明、参考说明、返回值说明。抛出异常说明等，这一部分最好和第二部分有一个空行，不然可能会出现错误。 ![Center 2][]

![Center 3][]

### 常用的javadoc标记及其使用 ###

![Center 4][]

**1、@see的使用：**

**    **@see的句法有三种

①、@see 类名

类名可以根据需要只写出类名，如String，或者写出全名：java.lang.String，但需要注意的是，在用类名的时候需要这个java源文件中import这个类，否则只能用全名。

②、@see\#方法名或属性名

如果是属性名，则只需要写出属性名即可，如果是方法名，则需要写出方法名以及参数类型，如果没有参数，也需要写出一对括号。

如：@see \#contains(Object)、@see \#count()、@see number

③、@see 类名\#方法名或属性名

如：@see Object\#equals(Object)、@see java.lang.String\#toString()

** 2、@author、@version的使用：**

这两个标记分别指明作者和版本号，缺省情况下javadoc自动将其忽略，但命令行开关-author和-version可以修改个功能，使其包含的信息流输出，这两个标记都可以多个使用，但是版本号只有第一个出现的有效。

**3、@param、@return和@exception的使用：**

这三个标记只能用于方法，@param描述参数，@return描述返回值，@exception描述抛出异常，用法如下：

①、@param 参数名 参数说明

每一个@param都只能描述一个方法的参数，可以多次使用。

②、@return 返回值说明

一个方法只能使用一个@return，如果有多个，javadoc会发出警告，并且只有第一个声明的有效。

@exception 异常类名 异常说明

@exception可以多次使用，并且异常的类名需要注意在java原文件中是否有导入，如果没有需要写类全名。

如：

/\*\* 
     \* test 方法的简述，这个方法用于做javadoc的测试. 
     \* test方法的详细说明，这里是详细说明的第一行 
     \* test方法详细说明的第二行 
     \*  
     \* @param a firstnum 
     \* @param b lastnum 
     \* @exception java.lang.ArithmeticException throw when b is 0 
     \* @return 返回值为a/b 
     \*/ 
    public int test(int a,int b) throws java.lang.ArithmeticException\{ 
        return a/b; 
    \}

\*注意：写文档注释的时候应该注意正确的匹配参数，javadoc在一定程度上不会检查我们写的文档注释，如果写错误可能会造成一些困惑

### javadoc命令 ###

** 用法：javadoc \[options\] \[packagenames\] \[sourcefiles\]**

** 选项：**

-public 仅显示 public 类和成员  
    -protected 显示 protected/public 类和成员 (缺省)  
    -package 显示 package/protected/public 类和成员  
    -private 显示所有类和成员  
    -d ＜directory＞ 输出文件的目标目录  
    -version 包含 @version 段  
    -author 包含 @author 段  
    -splitindex 将索引分为每个字母对应一 个文件  
    -windowtitle ＜text＞ 文档的浏览器窗口标题

javadoc可以给定包列表进行编译，如：javadoc xcg xcg.test

也可以给出源文件列表，如：javadoc xcg/test/JavaDocTest.java

以上两种方式的编译结果不同，用包列表生成的文档被框架分成了三个部分：包列表、类列表和类说明

在eclipse或myeclipse中可以使用file->Export->javadoc可以进行手动输出javadoc，需要注意生成的时候可能会出现错误: 编码GBK的不可映射字符，这时就需要在流程的最后一步加上一句话控制字符：-encoding UTF-8 -charset UTF-8，如：

![Center 5][]![Image 1][]

### 注释规范 ###

1、注释原则：

①注释形式统一

②注释内容准确简单

2、注释条件：

①基本注释（必须加）：类、接口的注释、构造函数的注释、方法的注释、全局变量的注释、字段/属性的注释

②特殊必须加的注释：典型算法、代码不清晰易懂时加注释、修改代码时需要加注释、在循环分支需要加注释、为他人提供的接口等信息必须加注释。

[Center]: /images/20220612/b2faddf3f180487c9ffb7b354cba035a.png
[Center 1]: https://img-blog.csdn.net/20170718214116722?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQveGNnMTMyNTY2/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center
[Image 1]: 
[Center 2]: /images/20220612/6ba26bda2415466f89cf409c817e8ed8.png
[Center 3]: /images/20220612/1e7f686620094fab88eb580cf8b4cc18.png
[Center 4]: /images/20220612/4b5ebc60e12e4a88bd920320a7e26761.png
[Center 5]: https://img-blog.csdn.net/20170718214249794?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQveGNnMTMyNTY2/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center