使用javadoc規範java開發文檔

      通常我們寫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....，這樣不是我們希望的。一般注釋可以分為類注釋、方法注釋、欄位注釋等。下面分別作簡單的介紹

1. 類注釋
   類注釋應該在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);
}