javadoc的写作

 

原文出自：http://blog.csdn.net/mingjava/archive/2004/07/25/51091.aspx 还不太会直接引用：P    通常我们写java程序可能很少会写注释的，但是在公司里真正开发项目的时候。通常都会有严格的文档要求，我这里谈到的不是设计或者测试文档，而是javadoc。我一直认为javadoc察看起来比MSDN要方便，写起来同样不复杂。   javadoc 是j2sdk里面一个非常重要的工具，如果你按照规范在java的源代码里面写好注释的话，那么它就可以生成相应的文档。开发者察看起来会非常方便。很多 IDE都可以直接生成javadoc的，这里介绍如何写javadoc以及如何在eclipse下生成javadoc。   javadoc通常从package、公开类或者接口、公开或者受保护的字段、公开或者受保护的方法提取信息。每条注释应该是以/**开始以*/结尾。例如  /**  *  * @param id the coreID of the person  * @param userName the name of the person   * you should use the constructor to create a person object  */  public SecondClass(int id,String userName)  {  this.id = id;  this.userName = userName;  } 注释应该写在要说明部分的前面，如上所示。并且在其中可以包括html的标记，如果上面没有标记 的话，那么you should usr the ......将会在javadoc里面紧跟@param userName....，这样不是我们希望的。一般注释可以分为类注释、方法注释、字段注释等。下面分别作简单的介绍  类注释 类注释应该在import语句的后面在类声明的前面，比如 package com.north.java;  /**  * @author ming  *  * this interface is to define a method print()   * you should implements this interface is you want to print the username   * @see com.north.ming.MainClass#main(String[])  */ public interface DoSomething {  /**  * @param name which will be printed  * @return nothing will be returned  *  */  public void print(String name); } 其中@author 和@see都是常用的注释 第一个表示作者，第二个表示参考的连接。   2.方法注释  方法注释要紧靠方法的前面，你可以在其中使用@param @return @throws等标签。例如  /**  *  * @param i  * @return true if ..... else false  * @throws IOException when reading the file ,if something wrong happened  * then the method will throws a IOException  */  public boolean doMethod(int i) throws IOException  {  return true;  }   3.字段注释  只有public的字段才需要注释，通常是static德，例如  /**  * the static filed hello  */  public static int hello = 1;   在eclipse中我们新建java project然后编写几个接口和类以后就可以用javadoc生成文档了，从菜单project选择generate javadoc，会出现一个向导，你按照他的提示一步一步的设定要求，最好他会问你是不是声称一个javadoc.xml，如果选择生成的话，他会在 doc下产生一个javadoc.xml，以后更新文档的时候你可以直接用ant运行javadoc.xml。选择完成后你可以发现在project里面出现了一个目录doc里面就是你的javadoc,想写出好的javadoc一个非常好的办法就是多参考java的api doc。养成一个好的编程习惯非常重要，何况这并不难。下面是我写着篇blog的代码和注释 /*  * Created on 2004-7-25  *  * TODO To change the template for this generated file go to  * Window - Preferences - Java - Code Style - Code Templates  */ package com.north.ming;  /**  * @author P2800  *  * TODO To change the template for this generated type comment go to  * Window - Preferences - Java - Code Style - Code Templates  */ public class MainClass {   public static void main(String[] args)  {  } } /*  * Created on 2004-7-25  *  * TODO To change the template for this generated file go to  * Window - Preferences - Java - Code Style - Code Templates  */ package com.north.ming;  import java.io.IOException;  /**  * @author P2800  *  * TODO To change the template for this generated type comment go to  * Window - Preferences - Java - Code Style - Code Templates  */ public class SecondClass {   /**  * the static filed hello  */  public static int hello = 1;  private int id;  private String userName;   /**  *  * @param id the coreID of the person  * @param userName the name of the person   * you should use the constructor to create a person object  */  public SecondClass(int id,String userName)  {  this.id = id;  this.userName = userName;  }   /**  * @return Returns the userName.  */  public String getUserName()  {  return userName;  }  /**  * @param userName The userName to set.  */  public void setUserName(String userName)  {  this.userName = userName;  }   /**  *  * @param i  * @return true if ..... else false  * @throws IOException when reading the file ,if something wrong happened  * then the method will throws a IOException  */  public boolean doMethod(int i) throws IOException  {  return true;  }  } /*  * Created on 2004-7-25  *  * TODO To change the template for this generated file go to  * Window - Preferences - Java - Code Style - Code Templates  */ package com.north.java;  /**  * @author ming  *  * this interface is to define a method print()   * you should implements this interface is you want to print the username   * @see com.north.ming.MainClass#main(String[])  */ public interface DoSomething {  /**  * @param name which will be printed  * @return nothing will be returned  *  */  public void print(String name); } 