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

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
	 */
	@Override
	public void teach() {
		// TODO Auto-generated method stub
		System.out.println("teacher:"+super.getNameString()+"teach"+this.courseString);
	}
	
}

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