Java（四）——Java的⽂档注释（使⽤javadoc⼯具⽣成API⽂档）Java注释
编写程序时，总要为程序添加⼀些注释，⽤以说明某段代码的作⽤，或者某个类的⽤途、某个⽅法的功能，以及该⽅法的参数及返回值的意义。
为什么要编写注释？主要有⼀下⼏个⽅⾯的考虑：
-永远不要过于相信⾃⼰的理解能⼒。当你思路流畅，进⼊编程境界时，你可能很快地实现某个功能。但在以后再次阅读这段代码时，可能会不知其所以然，因此为了时刻回当初编程时的思路，建议编写注释。
-可读性第⼀，效率第⼆。如今软件开发愈发复杂，进⾏⼀次开发往往不是⼀个⼈的⼯作，需要整个团队协同作战，团队队员之间就需要互相阅读他⼈的代码，编写注释就是为了能让他⼈更好更快地理解⾃⼰所编写的代码。其次，在后期维护时，仍然可以通过注释来掌握理解程序。从某种⾓度来说，这同样也提⾼了团队开发的效率。
-代码即⽂档！许多⼈认为，在软件开发中只有像《软件需求规格说明书》等⼀系列软件开发规范中的word⽂档才是⽂档。其实，开发⼈员编写的源代码也是⽂档的⼀部分，我们要把软件⾥最重要的⽂档——源代码写规范。
程序注释是源代码的重要组成部分，⼀份规范的程序源代码中，注释占到了源代码1/3以上。⼏乎所有的编程语⾔都会提供添加注释的⽅法，⼀般会有单⾏注释、多⾏注释。Java语⾔的注释⼀共有三种：
-单⾏注释（// 之后便是单⾏注释）
-多⾏注释（/* 在这之间都是注释，可跨多⾏ */）
-⽂档注释（/** 在这之间都是⽂档注释 */）
Java⽂档注释
可以利⽤Javadoc⼯具将Java源代码中的⽂档注释⾃动转化成API⽂档。
javadoc命令的基本⽤法如下：
javadoc 选项 java源⽂件|包
上述语法格式中，javadoc⽀持通配符，⽐如*.java就表⽰当前路径下所有java⽂件。javadoc常⽤选项有如下⼏个：-d(directory)：该选项指定⼀个路径，⽤于将⽣成的API⽂档放到指定⽬录下。
-windowtitle(text)：该选项指定⼀个字符串，⽤于设置API⽂档的浏览器窗⼝标题。
-doctitle(html-code)：该选项指定⼀个HTML格式的⽂本，⽤于指定概述页⾯的标题。
注意：只有对处于多个包下的源⽂件来⽣成API⽂档时，才有概述页⾯。
-header(html-code)：该选项指定⼀个HTML格式的⽂本，包含每个页⾯的页眉。
除此之外，javadoc命令还包含了⼤量其他选项，我们可以通过在命令⾏窗⼝执⾏javadoc -help命令来查看javadoc命令的所有选项。
接下来，看⼀个具体的例⼦吧：
⾸先，编写⼀个Javadoc类，包含了⽂档注释。
package com.star.main;
/**
* Description:
* This program is used to test javadoc.
* Program Name:
* Date:
* @author Undergoer
* @version 1.0
*/
public class JavadocTest {
/**
* 成员变量的⽂档注释
*/
protected String name;
/**
* main⽅法，程序⼊⼝
*/
public static void main(String[] args){
System.out.println("hello");
}
}
其次，编写⼀个Test类，这个类包含了对类、构造器、成员变量的⽂档注释。
package st;
/**
java修改html文件
* Description:
* This program is used to test javadoc.
* Program Name:
* Date:
* @author star
* @version 1.0
*/
public class Test {
/**
* 成员变量⽂档注释
*/
public int age;
/**
* Test类构造器的⽂档注释
*/
public Test(){}
}
在命令⾏窗⼝执⾏如下命令，来为刚刚编写的两个java程序⽣成API⽂档：
javadoc -d api_doc -windowtitle 测试API -doctitle 学习javadoc -header 我的类 *Test.java
在JavadocTest.java和Test.java所在路径下执⾏上⾯命令，可以看到⽣成API⽂档的提⽰信息。
进⼊此路径，可以看到⼀个api_doc⽂件夹，该⽂件夹下的内容就是刚刚⽣成的API⽂档，打开index.html⽂件，将看到如下图所⽰的页⾯。
同样，单击该页⾯左下⾓类列表区中的某个类，可以看到该类的详细说明。
除此之外，如果希望javadoc⼯具⽣成更详细的⽂档信息，例如为⽅法参数、⽅法返回值等⽣成详细的说明信息，则可以利⽤javadoc标记。常⽤javadoc标记如下：
@author：指定Java程序的作者
@version：指定源⽂件的版本
@depreated：不推荐使⽤的⽅法
@param：⽅法的参数说明信息
@return：⽅法的返回值说明信息
@see：“参见”，⽤于指定交叉参考的内容
@exception：抛出异常的类型
@throws：抛出的异常，和@exception同义
最后⼀点要说明的是，API⽂档类似于产品的使⽤说明书，通常只需要介绍那些暴露的、供⽤户使⽤的部分，在java类中就是以public或protected修饰的内容，因此javadoc默认只处理public或protected修饰的内容。如果开发者确实希望可以提取private修饰的内容，则可以在命令⾏使⽤javadoc⼯具时增加-private选项。还有，javadoc⼯具只处理⽂档源⽂件在类、接⼝、⽅法、成员变量、构造器和内部类之前的⽂档注释，忽略其他地⽅的⽂档注释。

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。