Android入门基础（5 ) Javadoc

Android入门基础（5）

----Javadoc使用

利用eclipse生产javadoc文档的步骤如下：

1.选择File->Export->javadoc，下一步。

2.Javadoc comand选择JDK的bin目录下的javadoc.exe。选择要生成的源代码和javadoc保存的目的路径，下一步。

3.Document title输入标题，下一步。

4.overview输入启动指定的overview文件路径，ExtraJavadoc options输入

-windowtitle 'Type B Monitor'[浏览器显示标题]

-bottom <center>Travelsky</center>[底部显示文本]，下一步。

Javadoc标签及基本功能使用：

Javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形式程序的开发文档了。
Javadoc输出的是一些HTML文件，我们可以通过WEB浏览器来查看它。
Javadoc的语法：
所有Javadoc都只能源于/**开始和*/结束。使用javadoc有二种方式：一种是嵌入HTML；另一种是使用文档标签。所谓文档标签就是一些以 “@”开头的命令，且“@”要置于注释行的最前面。而“行内文档标签”则可以出现在Javadoc注释中的任何地方，它们也是以“@”字符开头，但要括在共括号内。
Javadoc只能为public或者protected成员进行文档注释。private和包内访问的成员的注释会被忽略掉。这样做是有道理的，因为只有public和protected成员才能在文件之外被使用，这也体现了封装性的优点。
嵌入HTML：
Javadoc将HTML代码嵌入到所生成的HTML文件中。这样能充分利用HTML的功能。比如：

1. /** 

2. *<b> 

3. *thisismytestprogram; 

4. *</b> 

5. */

但一般我们不要在HTML里使用标题，如<h1><hr>，因为Javadoc会插入自己的标题，我们的标题可能会干扰它。
常用的标签：
1) @see：引用其它类的文档，相当于超链接，Javadoc会在其生成的HTML文件中，将@see标签链到其他的文档
@see classname
这样在生成的文档中会出现"See Also"的超链蛸。但是Javadoc不去检查你的超链接是否有效。
2){@linkpackage.class#member label}
与@See的功能一样，只是用label作主超链接，而不是用"see also"
3){@docRoot}：标签产生到文档根目录的相对路径，用于文档树页面的显式超链接
4){@inheritDoc}：标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。
5) @version：使用方法为@version 2.2.1.2...
2.2.1.2...是我们作的版本说明信息
6) @author：使用方法为 @author [e-mail]
也就是说我们可以在@author后加上作者名字，email等联系方式
7) @since：这个标签允许你指定程序最早使用的版本。
比如我们看JDK Document里的每个类最后都会说明从JDK哪个版本开始启用。
8) @param：@param name 用于输入客户的姓名
@param后面是方法的参数，以及相应的说明
我们可以使用任意数量的此标签，每个参数都可以有这样一个标签
9) @return this is description
@return后面是描述返回值的含义，可以延续几行。
10) @throws fully-qualified-class-name description
fully-qualified-class-name为异常类的完整名字，
而description告诉你为什么此异常会在方法中调用出现。
11) @deprecated：用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用旧特性。