[Java]文档及javadoc使用
2016-05-31 00:00
621 查看
摘要: Javadoc
加入文档和正确调试对任何编程语言来说都十分重要的。在 Java 这样的面向对象的语言中,好的文档和调试手段扮演着至关重要的角色。
为了帮助编程,JDK 不仅提供可以向源程序中插入实现方式的说明,而且提供了一个自动生成完整的、清晰的文档说明工具 javadoc。这些文档说明被保存为 HTML 格式,这样可以用任何浏览器浏览,而且该文档不包含源代码。
#实现说明和文档说明
##实现说明
我们可以在程序的复杂部分嵌入两种实现说明:
一种可以插入到一行的末尾,用来简要说明文档的用途。这样的说明起始于双斜线符号//。
另一种说明需要指定开始点和结束点,用于大段代码的说明。这样的说明起始于 “/” ,然后以 “/” 符号结束。
###正确的使用说明
编程技巧:不要给已经很清晰的代码加注释,按下面的方法写出尽可能清晰的代码:
使用合适的变量名来指明锁存数据的含义。
将一个大任务分成模块化的子任务。
用能清楚说明每个方法作用的名字为方法命名。
尽量将局部变量、成员变量和方法适当命名,以便生成流畅英语的句子。
偶尔也会遇到很难给一个方法命名的情况,那往往是因为该方法试图完成多项功能,我们应该试着把他分成多个清晰的子任务。
该方法使用了正确的注释说明其功能,但是方法名 changeString 太含糊,这显然不是好的编程方法。
与以上方式不同,下面的代码没有注释,却更清晰灵活。
我们将原方法分成命名清晰的两个方法,这样就不再需要注释。另外,我们可以加强移去首字符 # 的方法的功能,让他可以移去任何首字符。因为 String 类具有将字符转化成大写字符的方法,所以可以直接调用。
也可以把三句合并成一句:
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 注解的完整程序。
javadoc 生成的第一行文档说明描述了整个程序的作用。改说明包括 HTML 的标签用以指定代码段、作者名、版本号和日期。
两个方法的说明简要描述了这些方法要做什么。尤其是每个方法都有 @return 标签来说明返回值。
最后是对 main 方法的描述。他主要是用来测试前面的方法。
编程技巧:一个完整的程序或类应该包含适当的文档说明,而且,至少应该:
使用 javadoc 生成文档说明,给出整个类的作用的简明描述。
通过 @author 标签指出作者名。
通过 @version 指出版本号和代码的日期。
使用 javadoc 给类中的每个方法生成简明描述,指出方法的所有输入参数的含义和返回类型。弱方法的输入参数有特殊要求,也需要指出。
###javadoc 工具
javadoc 工具是 JDK 的一部分,它用来从 Java 源代码中分析并生成文档说明,他可以生成格式良好、交叉连接、具有索引的 HTML 文档。要使用 javadoc 工具,可以在命令行输入如下代码:
对文件名可以使用通配符。下面是一些可选项。
-private:显示所有类和成员。
-version:包括 @version 标签(缺省忽略)。
-author:包括 @author 标签(缺省忽略)。
javadoc 工具 缺省为每个 Java 源文件生成一个 HTML 文件、类层次文件 overview-tree.html 和索引文件 index.html。
前面我们创建了一个 javadoc 注释的程序。用 javadoc 生成 HTML 文档,然后用浏览器查看。当我们输入命令行:
为了包括作者和版本信息,我们要加上 -version 和 - author 选项:
该命令执行后创建一些文件,其中包括 StringsAndComments.html 文件。
这是直接用 Eclips 里的 javadoc 直接生成的图片。
加入文档和正确调试对任何编程语言来说都十分重要的。在 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 ```reverseString```and```removeLeadingChars<.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 <code>removeThis``` */ public static String removeLeadingChars(String s,char removeThis){ /*code as before*/ } /** *This main method texts ```removeLeadingChars```and```reverseString``` 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 文档,然后用浏览器查看。当我们输入命令行:
javadoc StringAndComments.java
为了包括作者和版本信息,我们要加上 -version 和 - author 选项:
javadoc -author -version StringAndComments.java
该命令执行后创建一些文件,其中包括 StringsAndComments.html 文件。
这是直接用 Eclips 里的 javadoc 直接生成的图片。
相关文章推荐
- Android Studio或者Eclipse中的最常用的快捷键,最简单的,部分不适用eclipse
- String Matching in the legend
- eclipse android程序运行报错:Conversion to Dalvik format failed: Unable to execute dex:
- 程序员软件开发最好的IDE集成工具eclipse各个版本的详细介绍。详细介绍,送给初学者的朋友
- AndroidStudio与eclipse打包的时候报错。Error:(4) Error: "ssdk_instapager_login_html" is not translated in...
- eclipse 设置默认编码为Utf-8 详细教程。
- Android开发之Eclipse与Android Studio的java类 作者版权模板
- Spring+SpringMVC+MyBatis+Maven框架整合
- java数组报错空指针 java.lang.NullPointerException
- java设计模式——责任链模式
- java设计模式——桥接模式
- spring mvc 的工作原理(1)DispatcherServlet 请求处理流程
- 使用Eclipse构建Maven的SpringMVC项目
- 建立Dynamic Web project转成Maven项目方法
- Spring事务配置
- Java线程(二):线程同步synchronized和volatile
- 枚举
- 泛型
- springmvc的上传功能
- Java Connection.setAutoCommit使用的注意事项