java生态系统：二、java文档注释

• 简介

      一段优良的代码，应该包含详尽的注释，java代码注释大概可以分为三大类：单行注释、多行注释、单行双下划线注释。

      java作为主流的面向对象语言，其支持一种称为javadoc注释的特殊类型文档注释机制，javadoc注释以/**开始，以*/结束。可以使用javadoc去描述一个类，一个接口，数据域或者方法。

      通过使用JDK的javadoc命令，可以将javadoc注释以HTML文件的形式输出。

• 实例演示

     如下所示，一段注释好的java类：

/** base class People,include the base attribute of a people*/public class People {/** data field:nameString*/private static String nameString;/** data field:addressString*/private static String addressString;/** data field:sex*/private static String sex;/** data field:age*/private static int age;/** method comment:return nameString*/public static String getNameString() {return nameString;}/** method comment:set nameString*/public static void setNameString(String nameString) {People.nameString = nameString;}/** method comment:return addressString*/public static String getAddressString() {return addressString;}/** method comment:set addressString*/public static void setAddressString(String addressString) {People.addressString = addressString;}/** method comment:return sex*/public static String getSex() {return sex;}/** method comment:get sex*/public static void setSex(String sex) {People.sex = sex;}/** method comment:return age*/public static int getAge() {return age;}/** method comment:set age*/public static void setAge(int age) {People.age = age;}}

      eclipse生成javadoc步骤：

      （1）选中项目，邮件选中Export选项

      （2）在输出选项中，选择java下面的javadoc选择项，下一步next

      （3）在javadoc Generation对话框中，javadoc command设置为jdk安装目录中的bin/javadoc.exe,设置好生成路径，finish完成javadoc生成工作

      （4）在生成javadoc的目录中，打开index.html文件，如下所示：

• javadoc标签

      在注释中，你能够使用javadoc标签来指定所要描述信息的类型。常使用的标签如下所示：

      @author[author name]: 指定类或者接口的作者。

      @version [version]:给定一个类或者接口的版本。

      @param [parameter name][parameter description]:描述一个方法或者构造器中参数。 

      @return [description of return]:从一个方法中返回一个值。

      @exception [exception thrown][exception description]:描述从一个方法或者一个构造器中抛出的异常。

      @override 标识为覆写方法或者构造器

      @overload标识为重载方法或者构造器 

      示例代码如下所示：

public class Teacher extends People implements Teachable {/** data field:courseString*/private String courseString; /** * @author wenjerzhan(http://blog.csdn.net/wenjerzhan) * @version 1.0 * @param nameString 姓名 * @param addressString地址 * @param sex性别 * @param courseString课程 * @param age年龄 */private Teacher(String nameString,String addressString,String sex,String courseString,int age){super.setNameString(nameString);super.setAddressString(addressString);super.setSex(sex);super.setAge(age);this.courseString = courseString;}/** * @see http://blog.csdn.net/wenjerzhan */@Overridepublic void teach() {// TODO Auto-generated method stubSystem.out.println("teacher:"+super.getNameString()+"teach"+this.courseString);}}

      使用相同的javadoc生成步骤，得到javadoc如下所示：