第二章 java基础(javadoc注释)

—— 本文参照 Learn Java for Android Development (第三版)

** javadoc 注释 **
在其他的编程语言里面我们一般只会使用到上一篇介绍到的单行或者多行注释的方式，但是在java里面还有第三种注释方法：javadoc，这种方式使用起来也是非常方便的。使用以后你会发现这不仅对我们自己开发会带来便捷，同时它也给那些基于我们程序开发的小伙伴带来很多好处呢。
javadoc的注释跟多行注释一样会占据一行或者多行，它以这个符号，所有存在这两个符号之间的内容就是注释，都会被编译器忽略掉。下面的例子就是一个javadoc的范例：

public static void main(String[] args)
{
// TODO code application logic here
}
这里的注释主要是描述了一下main函数。夹在中间的就是具体的描述内容，@param是一个javadoc的标签，用来通知javadoc工具的。
下面说几个经常会使用到的javadoc的标签：
■ @author 表示源码的作者
■ @deprecated 标识一些已经过时的代码
■ @param 表示函数的一个参数
■ @see 仅供参阅
■ @since 表示软件第一个版本发布的情况
■ @return 函数的返回值
■ @throws 记录函数运行过程中发生的异常
再示范一个大家比较熟悉的例子，用javadoc来注释：

public class DumpArgs
{

public static void main(String[] args)
{
System.out.println("Passed arguments:");
for (int i = 0; i < args.length; i++)
System.out.println(args[i]);
}
}
我们可以使用javadoc工具把这些文档注释转化为html格式：
javadoc DumpArgs.java
然后javadoc会有如下的打印信息：
Building index for all the packages and classes...
Generating \overview-tree.html...
Generating \index-all.html...
Generating \deprecated-list.html...
Building index for all classes...
Generating \allclasses-frame.html...
Generating \allclasses-noframe.html...
Generating \index.html...
Generating \help-doc.html...
然后会生成几个文件，包括index.html，在浏览器里面打开这个文件，会看到如下图的内容：