Javadoc的基本使用

一、什么是Javadoc

Javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的HTML格式的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。这种文档可以告诉使用你的程序或类的用户在忽略所有实现细节的情况下如何使用这些程序或类，这些细节包括所有（公有或私有）方法的定义体、所有与私有方法相关的信息以及所有私有的实例变量。

javadoc通常情况下会用于包，尽管它也可以用于单个类。你需要具有对HTML浏览器（Web浏览器）的访问权限，这样才能浏览由javadoc生成的文档。但是，使用javadoc并不需要非常了解HTML。

二、Javadoc的基本使用

1 使用javadoc进行注释

为了获得有用的javadoc文档，必须按照特定的方式编写注释。javadoc会抽取这些注释，以及类头和所有公有方法头与公有实例变量。它不会抽取任何方法体或私有项。

为了让javadoc可以抽取某条注释，这条注释必须：

• 紧靠公有类定义、公有方法定义或其他公有项的前面。
• 以 /** 开头，并且以 */ 结尾

我们称这些注释为javadoc注释。注意，以 // 开头的注释和任何私有项前面的注释都不会被抽取。

在javadoc注释中，可以使用标签来标识和描述像方法参数和返回值这样的东西。下面展示了一些标签的使用语法：

@param parameter_Name Parameter_Description
@return Description_Of_Value_Returned
@throws Exception_Type Explanation

每个标签都是以@符号开头的，并且会在注释中另起一行。在使用上面的三种标签时，它们必须按照上面给出的顺序出现。可以删除任何无关的标签，也可以在需要时多次使用同一个标签。

例如，下面的方法就具有一条有效的javadoc注释：

/**
Computes the total cost of mutiple identical items.
@param number number of items purchased
@param price cost of one item
@return total cost of all items at given price per item
*/
public static double computeCost(int number, double price)
{
	return number * price;
}

javadoc从此注释生成的文档会显示如下：

 ComputeCost
 public static double computeCost(int number, double price)
 	Computes the total cost of mutiple identical items.
 	Parameters:
 		number - number of items purchased
 		price - cost of one item
 	Returns:
 		total cost of all items at given price per item

你还可以在你的注释中插入HTML命令，使得你可以获得更多对javadoc的控制权，但是这不是必需的，甚至有时并不是我们想要的。HTML命令会使注释变得凌乱，使得你在查看源代码时，更难以阅读他们。

Javadoc常用标记

Javadoc规范

• 类： 每个类必须包含描述文本、@author(作者名称)、 @version(版本号) 和@date(日期)注解

• 方法：每个方法必须包含描述文本

   1、带有参数的方法：必须包含@param注解
   2、可能会抛出异常的方法： 必须包含@throws或者@exception注解
   3、带有返回值的方法： 必须包含@return 方法
   4、不再使用的方法：如果为了兼容性继续存在，则必须使用@deprecated 进行注解
  

• 变量：如果为成员变量则必须使用javadoc进行注解

• 常量：如果为成员常量则必须使用javadoc进行注解（常量最好修饰为静态并加上@value注解）

2 运行javadoc

如果想要在单个类上运行javadoc，可以直接在这个类的开头插入下面这行语句，将这个类放入一个包中：

package Package_Name;

包名描述的是相对于包含包中文件的目录或文件夹的相对路径名。

为了运行javadoc，你必须位于包含了你想要生成文档的文件夹中，而不是位于包文件夹中。然后，只需给出下面的命令：

javadoc -d Document_Folder Package_Name

Document_Folder 是你想让javadoc放置它所产生的HTML文档的文件夹名。

你可以在命令行中包含一个选项，告诉javadoc在文档中包含对标准类和方法的实时链接，其语法如下：

javadoc -link Link_To -d Document_Directory Package_Name

Link_To要么是Java文档的本地版本的路径，要么是Oracle网站上标准Java文档的URL。