java doc

以下文字参考自

 

javadoc工具可以从以下4类“源文件”产生doc：
(1) java源文件(.java),生成对类和类的成员的doc
(2) package注释文件(package-info.java或者package.html),生成对包的说明
(3) overview文件(名可以随便，通常是overview.html),生成对整个应用程序或者是一组包的说明
(4) Miscellaneous Unprocessd files (各种不被处理的文件，如图像图标等；放在doc-files目录底下)，这些文件可以被前面3类“源文件”引用。

 

说明
(1) java源文件里的注释格式大致如下
/**
 *  一句话的简介.
 * 

 *  详细说明
 * 
*/

可以在注释里添加javadoc tags,具体细节参见http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#documentationcomments

 

(2) package注释
1, package-info.java
如: cn/edu/mypackage/package-info.java
/**
 * 对包的一句话简介
 *

 * 详细说明
 *
 */

注意：在package-info.java里/**和*/是必须的，如果使用eclipse开发，最好新建文件(新建类会提示类名错误)，启名package-info.java

 

2，package.html
如：cn/edu/mypackage/package.html


对包的一句话简介

详细说明

 

注意：在package.html不要使用/**和*/

 

package注释里可以添加javadoc tag,具体细节参见http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#documentationcomments

 

(3) overview文件
一般放在源文件目录树的根，如：源文件均放在src目录下，可以把overview.html置在src下；使用javadoc工具生成doc时加上-overview选项，如果在eclipse里export->javadoc时，选上overview选项，指定overview文件。
overview文件格式与package.html类似，还以使用overview tags,具体参见

 

(4) Miscellaneous Unprocessd files
各种不被javadoc处理的文件，如image文件,.class文件,示例代码，.html文件等；放在doc-files目录底下，doc-files目录必须放在包目录下。例：包cn.edu.mypackage，则doc-files应该放在cn/edu/mypackage目录下，而cn.edu可能不是包，doc-files目录就不能放在cn/edu目录下。
doc-files目录底下的文件可以被引用，如，在包cn.edu.mypackage下，package-info.java里引用该包下doc-files里的一个.jpg的图像文件：
   /**
     * some comments present here
     *
     */