[java] view plaincopy
- package com.frank.chapter1;
- // object.Documentation1.java
- // TIJ4 Chapter Object, Exercise 13 - 1
- /* Run Documentation1.java, Documentation2.java and Documentation3.java
- * through Javadoc. Verify the resulting documentation with your Web browser.
- */
- /** A class comment */
- public class Documentation1 {
- /** A field comment */
- public int i;
- /** A method comment */
- public void f() {
- }
- }
如上一段代码，使用了javadoc的注释形式，注释以/** 开始, 以*/ 结尾，注释写在要说明部分的前面。
如何生成javadoc呢？ 很简单，在eclipse中点击导航栏中的 project->Generate javadoc
跳出如下界面，然后勾选需要生成文档的包以及生成文档的位置就OK啦！~
更详细的说明见转载
以下转自：http://blog.csdn.net/heavenying/archive/2007/05/31/1632348.aspx
通常我们写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。养成一个好的编程习惯非常重要，何况这并不难。