java基础（4）：java注释-蒲公英云

java里有两种注释风格。一种是传统的C语言风格的注释--C++也继承了这种风格。此种注释以“/\*”开始，随后是注释内容，并可跨越多行，最后以“\*/”结束。注意，许多程序员在连续的注释内容的每一行都以一个“\*”开头，所以经常看到像下面的写法：
/*
     * 这是多行注释
     * 
     */
但请记住，进行编译时，/\*和\*/之间的所有东西都会被忽略，所以上述注释与下面这段注释并没有什么两样：
/*
     这是多行注释
     */
第二种风格的注释也源于C++。这种注释是“单行注释”，以一个“//”起头，直到句末。这种风格的注释因为书写容易，所以更方便、更常用。你无需在键盘上寻找“/”，再寻找“\*"（只需按两次相同的键），而且不必考虑结束注释。例如：
// 这是单行注释

一、注释文档

代码文档撰写的最大问题，大概就是对文档的维护了。如果文档与代码时分离的，那么在每次修改代码时，都要修改相应的文档，这会成为一件相当乏味的事情。解决的方法似乎很简单：将代码同文档“连接起来”。为了达到这个目的，最简单的办法是将所有东西都放在同一文件内。然而，为实现这一目的，还必须使用一种特殊的注释语法来标记文档；此外还需一个工具，用于提取那些注释，并将其转换成有用的形式。这正是java所做的。
javadoc便是用于提取注释的工具，它是jdk安装的一部分。它采用了java编译器的某些技术，查找程序内的图书注释标签。它不仅解析由这些标签标记的信息，也将毗邻注释的类名或方法名抽取出来。如此，我们就可以用最少的工作量，生成相当好的程序文档。
javadoc输出的是一个HTML文件，可以用WEB浏览器查看。这样，该工具就使得我们只需创建和维护单一的源文件，并能自动生成有用的文档。有了javadoc，就有了创建文档的简明直观的标准；我们可以期望、甚至要求所有的java类库都提供相关的文档。

（1）语法

所有javadoc命令都只能在“/\*\*”注释中出现，和通常一样，注释结束于“\*/”。使用javadoc的方式主要有两种：嵌入HTML，或使用“文档标签”。独立文档标签是一些以“@”字符开头的命令，且要置于注释注释行的最前面（但是不算前导“\*”之后的最前面）。而“行内文档标签”则可以出现在javadoc注释中的任何地方，它们是以“@”字符开头，但要括在花括号内。
共有三种类型的注释文档，分别对应于注释位置后面的三种元素：类、域和方法。也就是说，类注释正好位于类定义之前；域注释正好位于域定义之前；而方法注释也正好位于方法定义的前面。例如：
/**
 * 类注释
 */
public class Documentation {
    /**
     * 域注释
     */
    public int i;
    /**
     * 方法注释
     */
    public void f() {
    }
}
注意，javadoc只能为public（公共的）和protected（受保护的）成员进行文档注释。private（私有的）和包内可访问成员的注释会被忽略掉，所以输出结果中看不到它们。这样做是有道理的，因为只有public和protected成员才能在文件之外被使用，只是客户端程序员所期望的。

（2）eclipse生成注释文档

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70 1

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70 2

这里加上一个：-encoding UTF-8 -charset UTF-8，可以解决编码GBK不可映射字符问题

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70 3

上述代码的输出结果是一个HTML文件，它与其他java文档具有相同的标准格式。因此，用户会非常熟悉这种格式，从而方便的导航到用户自己设计的类。输出上述代码，然后通过javadoc处理产生HTML文件，最后通过浏览器换看生成的结果，这样做是非常值得的。

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70 4

" class="reference-link">

注意：在eclipse里选择java类按shift+f2可以查看该类文档。如查看String类：

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70 6

#

二、嵌入式HTML

javadoc通过生成的HTML文档传送HTML命令，这使你能够充分利用HTML。当然，其主要目的还是为了对代码进行格式化，例如：
/**
 * <pre>
 *     System.out.println(new Date());
 * </pre>
 */
也可以像在其他WEB文档中那样运用HTML，对普通的文本按照你自己所描述的进行格式化：
/**
 * You can <em>even</em> insert a list:
 * <ol>
 *     <li>队列1</li>
 *     <li>队列2</li>
 *     <li>队列3</li>
 *</ol>
 */
注意，在文档注释中，位于每一行开头的星号和前导空格都会被javadoc丢弃。javadoc会对所有内容重新格式化，使其与标准的文档外观一致。不要在嵌套式HTML中使用标题标签，例如：<h1>或<hr>，因为javadoc会插入自己的标题，而你的标题可能同它们发生冲突。
所有类型的注释文档--类、域和方法--都支持嵌入式HTML。

三、doc标签

这里将介绍一些可用于代码文档的javadoc标签。在使用javadoc处理重要事情之前，应该先到jdk文档那里查阅javadoc参考，以学习javadoc的各种不同的使用方法。

（1）@see：引用其他类

@see标签允许用户引用其他类的文档。javadoc会在其生成的HTML文件中，通过@see标签链接到其他文档中。

（2）@link

该标签与@see极其相似，只是它用于行内，并且使用“label”作为超链接文本而不用“See Also”

（3）@docRoot

该标签产生到文档根目录的相对路径，用于文档树页面的显示超链接。

（4）@inheritDoc

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

（5）@version

该标签使用格式：@version version-information，其中“version-information”可以是任何你认为合适包含在版本说明中的重要信息。如果javadoc命令行使用了“-version”标记，那么就从生产的HTML文档中特别提取出版本信息。

（6）@author

 该标签使用格式：@author author-information，作者。但是也可以包括电子邮件地址或其他任何适宜的信息。如果javadoc命令行使用了-author标记，那么就从生成的HTML文档中特别提取作者信息。可以使用多个标签，以便列出所有作者，但是它们必须连续放置。全部作者信息会合并到同一段落，置于生成的HTML中。

（7）@since

该标签允许你指定程序代码最早使用的版本，可以在HTML java文档中看到它被用来指定所用的JDK版本情况。

（8）@param

该标签用于方法文档中，使用格式：@param parameter-name description。其中parameter-name是方法的参数列表中的标识符，description是可延续数行的文本，终止于新文档标签出现之前。可以使用任意多个这种标签，大约每个参数都有一个这样的标签。

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70 7

（9）@return

该标签用于方法文档中，使用格式：@return description。其中description用来描述返回值的含义，可以延续数行。

（10）@throws

它们是由于某个方法调用失败而“抛出”的对象。尽管在调用一个方法时，只出现一个异常对象，但是某个特殊方法可能会产生任意多个不同类型的异常，所有这些异常都需要进行说明。使用格式：@throws fully-qualified-class-name description。fully-qualified-class-name给出一个异常类的无歧义的名字，而该异常类在别处定义。description告诉你为什么此特殊类型的异常会在方法调用中出现。

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMjk4MzUx_size_16_color_FFFFFF_t_70 8

（11）@deprecated

该标签用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，因为在不久的将来它们很可能会被删除。如果使用一个标记为@deprecated的方法，则会引起编译器发布警告。
在java SE5中，javadoc标签@deprecated已经被@Deprecated注解所替代。

四、文档示例

再次回到第一个java程序，但是这次加上了文档注释：
/**
 * 这是一个java实例，该类输出一个当前时间的字符串
 *    @author 游王子
 *    2020年1月15日 下午2:26:48
 */
public class HelloDate {
    /**
     * 程序的入口
     * @param args 命令行参数
     */
    public static void main(String[] args) {
        System.out.println("你好，今天是：");
        System.out.println(new Date());
        System.out.println("A String of things");
    }
}

五、编码风格

在“java编程语言编码约定”中，代码风格是这样规定的：类名的首字母要大写；如果类名有几个单词构成，那么把它们并在一起（也就是说不要使用下划线来分隔名字），其中每个内部单词的首字母都采用大写形式。例如：
public class AllTheColorsOfTheRainbow {}
这种风格有时称作“驼峰风格”。几乎其他所有内容--方法、字段以及对象引用名等，公认的风格与类的风格一样，只是标识符的第一个字母采用小写。例如：
public class AllTheColorsOfTheRainbow {
    int anIntegerRepresentingColors;
    void changeTheHueOfTheColor(int newHue) {
    }
}
当然，用户还必须键入所有这些长名字，并且不能输错，因此，一定要格外仔细。