手机游戏程序开发
上QQ阅读APP看本书，新人免费读10天
设备和账号都新为新人
上一章目录下一章

2.2 Java的程序注释

对于Java语言，最体贴的一项设计就是它并没有打算让人们为了写程序而写程序，人们需要考虑程序的文档化问题。对于程序的文档化，最大的问题莫过于对文档的维护。若文档与代码分离，那么每次改变代码后都要改变文档，这无疑会变成相当麻烦的一件事情。解决的方法看起来很简单：将代码同文档连接起来。为达到这个目的，最简单的方法是将所有内容都置于同一个文件中。然而，为使一切都整齐划一，还必须使用一种标准的注释语法，以便标记出特殊的文档；另外还需要一个工具，用于提取这些注释，并按有价值的形式将其展现出来。这些都是Java必须做到的。

用于提取注释的工具是javadoc。它采用了部分来自Java编译器的技术，查找置入程序的特殊注释标记。它不仅提取由这些标记指示的信息，也将相邻注释的类名或方法名提取出来。这样一来，就可用最小的工作量，生成十分专业的程序文档。

javadoc输出的是一个HTML文件，可用Web浏览器查看。该工具允许创建和管理单个源文件，并生成有用的文档。由于有了javadoc，所以能够用标准的方法创建文档。由于使用它非常方便，所以能轻松获得所有Java库的文档。

1．具体语法

所有javadoc命令都只能出现于“/**”注释中，但与平常一样，注释结束于“*/”。主要通过两种方式来使用javadoc：嵌入的HTML或使用“文档标记”。其中，“文档标记”（Doc tags）是一些以“@”开头的命令，置于注释行的起始处（但前导的“*”有时会被忽略）。

有三种类型的注释文档，它们对应于位于注释后面的元素：类、变量或方法。也就是说，类注释正好位于类定义之前；变量注释正好位于变量定义之前；方法注释正好位于方法定义的前面。如下所示。

            /** 一个类注释 */
            public class docTest {
            /** 一个变量注释 */
            public int i;
            /** 一个方法注释 */
            public void f() {}
            }

注意，javadoc只能为public（公共）和protected（受保护）成员处理注释文档。private（私有）和“友好”（详见第3 章）成员的注释会被忽略，看不到任何输出（也可以用private标记包括private成员）。这样做是有道理的，因为只有public和protected成员才可在文件之外使用，这是客户程序员所希望的。然而，所有类注释都会包含到输出结果里。

上述代码的输出是一个HTML文件，与其他Java文档具有相同的标准格式。因此，用户会非常熟悉这种格式，可在设计的类中方便地“漫游”。设计程序时，请务必考虑输入上述代码，用javadoc处理一下，观看最终HTML文件的效果。

2．嵌入HTML

javadoc将最终生成HTML文档，这便于使用户能够充分利用HTML的性能。当然，最后的目的是格式化代码，如下所示。

            /**
            *
            * System.out.println("Hello World!");
            *
            */
            /**
            *甚至可以插入一个列表：
            *
            *项目一
            *项目二
            *项目三
            *
            */

注意，在文档注释中，位于一行最开头的星号会被javadoc丢弃，同时被丢弃的还有之前的空格。javadoc会对所有内容进行格式化，使其与标准的文档外观相符。不要将这样的标题当做嵌入HTML使用，因为javadoc会插入自己的标题，用户给出的标题会与之冲突。所有类型的注释文档：类、变量和方法，都支持嵌入HTML文档。

3．@see：引用其他类

所有三种类型的注释文档都可包含@see标记，它允许引用其他类里的文档。对于这个标记，javadoc会生成相应的HTML，将其直接链接到其他文档。格式如下：

@see类名

@see完整类名

每一格式都会在生成的文档里自动加入一个超链接的“See Also”（参见）条目。注意javadoc不会检查指定的超链接，不会验证它们是否有效。

4．类文档标记

随同嵌入HTML和@see引用，类文档还可以包括用于版本信息及作者姓名的标记。类文档也可以用于接口为目的（后面会讲到）。

（1）@version

格式如下：

@version版本信息

其中，版本信息代表任何适合作为版本说明的资料。若在javadoc命令行使用了version标记，就会从生成的HTML文档里提取出版本信息。

（2）@author

格式如下：

@author作者信息

其中，作者信息可以包含姓名、电子邮件地址或其他任何资料。如果在javadoc命令行使用了author标记，就会专门从生成的HTML文档里提取出作者信息。可为一系列作者使用多个这样的标记，但它们必须连续放置。全部作者信息会一起存入最终HTML代码的单独一个段落里。

5．变量文档标记

变量文档只能包括嵌入HTML文档及@see引用。

6．方法文档标记

除嵌入HTML和@see引用之外，方法还允许使用针对参数、返回值及异常等的文档标记。

（1）@param

格式如下：

@param参数名 说明

其中，参数名指参数列表内的标识符，而说明代表一些可延续到后续行内的说明文字。一旦遇到一个新文档标记，就认为前一个说明结束。可使用任意数量的说明。

（2）@return

格式如下：

@return说明

其中，说明指返回值的含义，它可延续到后面的行内。

（3）@exception

有关异常（exception）的详细情况，会在以后的章节中具体讲述。简单来说，它们是一些特殊的对象，若某个方法失败，就可将它们“抛出”。调用一个方法时，尽管只有一个异常对象出现，但一些特殊的方法也许能产生任意数量的、不同类型的异常。所有这些异常都需要说明。所以，异常标记的格式如下：

@exception完整类名 说明

其中，完整类名明确指定了一个违例类的名字，它是在其他某个地方定义好的。而说明（同样可以延续到下面的行）告诉用户为什么这种特殊类型的违例会在方法调用中出现。

（4）@deprecated

该标记用于指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能抛弃这一功能。若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。

上一章目录下一章