[Java]文档及javadoc使用_html/css_WEB-ITnose

加入文档和正确调试对任何编程语言来说都十分重要的。在 Java 这样的面向对象的语言中，好的文档和调试手段扮演着至关重要的角色。为了帮助编程，JDK 不仅提供可以向源程序中插入实现方式的说明，而且提供了一个自动生成完整的、清晰的文档说明工具 javadoc。这些文档说明被保存为 HTML 格式，这样可以用任何浏览器浏览，而且该文档不包含源代码。

实现说明和文档说明

实现说明

我们可以在程序的复杂部分嵌入两种实现说明：

• 一种可以插入到一行的末尾，用来简要说明文档的用途。这样的说明起始于双斜线符号//。

• 另一种说明需要指定开始点和结束点，用于大段代码的说明。这样的说明起始于 “/ ” ，然后以 “ /” 符号结束。

正确的使用说明

编程技巧：不要给已经很清晰的代码加注释，按下面的方法写出尽可能清晰的代码：

• 使用合适的变量名来指明锁存数据的含义。
• 将一个大任务分成模块化的子任务。
• 用能清楚说明每个方法作用的名字为方法命名。
• 尽量将局部变量、成员变量和方法适当命名，以便生成流畅英语的句子。

偶尔也会遇到很难给一个方法命名的情况，那往往是因为该方法试图完成多项功能，我们应该试着把他分成多个清晰的子任务。

/*该方法反写一个字符串并且去掉首部的 # 符号，然后把字符串改写成大写字母，再返回新的转化后的字符串*/    public static String chandeString(String s){    //首先，反写字符串    String changedS = " ";    for(int i = s.length() - 1;i >= 0; i--)        changedS += s.charAt(i);    //接下來，去掉首部的加重号    while ((changedS.length() > 0) && (changedS.charAt(0) == '#'))        changedS = changedS.substring(1,changedS.length());    //最後，將其转化成大写字母    changedS = changedS.toUpperCase();    //返回转化后的字符串    return changedS;} 

该方法使用了正确的注释说明其功能，但是方法名 changeString 太含糊，这显然不是好的编程方法。与以上方式不同，下面的代码没有注释，却更清晰灵活。

    public static String reveserseString(String s){String reverseS = " ";for(int i = s.length() - 1;i >= 0; i--)    reverseS += s.charAt(i);return reverseS;}public static String removeLeadingChars(String s,char removeThis){while ((s.length() > 0) && (s.charAt(0) == removeThis))    s = s.substring(1,s.length());return s;} 

我们将原方法分成命名清晰的两个方法，这样就不再需要注释。另外，我们可以加强移去首字符 # 的方法的功能，让他可以移去任何首字符。因为 String 类具有将字符转化成大写字符的方法，所以可以直接调用。

String s = "# Otto";String convert = removeLeadingChars(s,'#');convert = reverseString(convert);convert = convert.toUpperCase(); 

也可以把三句合并成一句：

String s = "# Otto";String convert = reverseString(removeLeadingChars(s,'#')).toUpperCase(); 

Java 也可以使用 JDK 工具 javadoc，自动生成一个类的 HTML 文档。如果一个类会在其它场合下重用，那么就应该用 javadoc 生成相应的文档说明。

文档说明

Java 可以为源代码添加文档说明，可以用 JDK 开发包的 javadoc 工具来编译和排版。这个工具可以按如下规则从程序的源代码抽取一些标签式的注释，并将其处理、排版、索引以及交叉链接成 HTML 文档。

• 文档说明开始于符号 /* *,结束于符号 */。
• 文档说明可以包括 HTML 格式命令（directives）（除了标题标签）。
• 文档说明直接出现在他们引用的类名，变量或方法之前。
• 文档说明可以包括特殊的命令（directives）行。 @author Name：说明代码的作者。 @version Number/Date：用于指出版本号和代码完成日期。 @see class#references：用于链接其它的文档说明。
• 一个方法文档说明也可以包括如下命令（directives)。 @return rType：用于指出方法的返回类型。 @exception exType：用于指出方法所抛出的异常。

使用 Javadoc 建立说明文档

我们已经创建了 reverseString 和 removeLeadingChars 方法，用 javadoc 给这些方法建立文档说明。下面是嵌入了 javadoc 注解的完整程序。

/**This is a text program to text the methods reverseStringandremoveLeadingChars<.code>.*@author B G .W*@version 2016/5/29*/public class StringAndComments {    /**    *This method reverses the input string,i.e.the input string is returned character by character in reverse order.    *@return String    */    public static String reverseString(String s) {            /*code as before*/    }    /***This method removes all leading characters from the input string s .The character to be removed is determined by the input parameter removeThis*/    public static String removeLeadingChars(String s,char removeThis){    /*code as before*/}    /***This main method texts removeLeadingCharsandreverseString to see if they work correctly.*@see StringAndComments#removeLeadingChars(string,char)*@see StringAndComments#reverseString(String)*/    public static void main(String args[]){    String s = "#Otto";    String uncommented = removeLeadingChars(s,'#');    String upper = reverseString(uncommented).toUpperCase();    if(s.toUpperCase().equals(upper))        System.out.println("String is a palindrome");}} 

javadoc 生成的第一行文档说明描述了整个程序的作用。改说明包括 HTML 的标签用以指定代码段、作者名、版本号和日期。

两个方法的说明简要描述了这些方法要做什么。尤其是每个方法都有 @return 标签来说明返回值。

最后是对 main 方法的描述。他主要是用来测试前面的方法。

编程技巧：一个完整的程序或类应该包含适当的文档说明，而且，至少应该：

• 使用 javadoc 生成文档说明，给出整个类的作用的简明描述。
• 通过 @author 标签指出作者名。
• 通过 @version 指出版本号和代码的日期。
• 使用 javadoc 给类中的每个方法生成简明描述，指出方法的所有输入参数的含义和返回类型。弱方法的输入参数有特殊要求，也需要指出。

javadoc 工具

javadoc 工具是 JDK 的一部分，它用来从 Java 源代码中分析并生成文档说明，他可以生成格式良好、交叉连接、具有索引的 HTML 文档。要使用 javadoc 工具，可以在命令行输入如下代码：

javadoc [options]SourceCodeFile.java

对文件名可以使用通配符。下面是一些可选项。

-private：显示所有类和成员。

-version：包括 @version 标签（缺省忽略）。

-author：包括 @author 标签（缺省忽略）。

javadoc 工具 缺省为每个 Java 源文件生成一个 HTML 文件、类层次文件 overview-tree.html 和索引文件 index.html。

前面我们创建了一个 javadoc 注释的程序。用 javadoc 生成 HTML 文档，然后用浏览器查看。当我们输入命令行：

javadocStringAndComments.java 

为了包括作者和版本信息，我们要加上 -version 和 – author 选项：

javadoc -author -versionStringAndComments.java 

该命令执行后创建一些文件，其中包括 StringsAndComments.html 文件。

这是直接用 Eclipse 里的 javadoc 直接生成的图片。