javadoc的写作

转载 2006年06月23日 10:00:00


 

原文出自: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);
}


Javadoc的写作规范

1.类注释应该是一个完整、简洁的句子,以英文句号结束 2.方法注释 @deprecated,标识从某版本开始避免使用,并给出替代的链接 @deprecated  As of JDK 1.1, r...

Java IDE中设置作者日期等Javadoc注释信息

在Java的IDE(Integrated Development Environment,集成开发环境)中,如Eclipse、Spring Tool Suite、IntelliJ IDEA等,...
  • czh500
  • czh500
  • 2016年06月21日 19:38
  • 3271

Java的三种注释 Javadoc标记*

三种注释方法:   1、单行注释   //注释的内容   2、多行注释  /*......*/   3、/**......*/,这种方式和第二种方式相似。这种格式是为了便于javadoc程序自动生成文...

javadoc生成说明文档

JDK中可执行命令:javadoc和相关参数如下: C:\Users\123>javadoc javadoc: 错误 - 未指定程序包或类。 用法: javadoc [options] [pac...

java小例子:使用javadoc工具生成API文档

Javadoc命令可对源文件、包生成API文档,javadoc命令的基本用法如下: javadoc  选项 Java源文件/包 javadoc的常用选项有一下几个: -d:该选项指定一个路径,用...

手把手教你使用 idea 生成漂亮的 javadoc 文档

1、打开 idea,点击 Tools-> Generate JavaDoc…这样会打开生成 javadoc 文档的配置页面。2、进行配置:标注的是重要的部分,从上往下分别是配置 javadoc 的范围...

Eclipse中javadoc的使用以及中文乱码的解决

在使用Eclipse的时候有一个很方便使用的功能,那就是自动生成javadoc,但是在实际使用过程中发现,如果配置不当,会导致生成的doc文件中出现中文乱码. 研究后解决问题如下: 1,在...

maven——install、package等命令,忽略javadoc生成

博客分类:  我的JDK是最新的jdk8,maven工程配置的jdk是jdk6,在工程上执行install、package等命令会出现如下的一些信息,还有错误,导致执行命令不...
  • dotedy
  • dotedy
  • 2015年11月17日 18:29
  • 1530

Javadoc转换chm帮助文档的四种方法总结

朋友,当您在一个项目完成后,是不是需要把你的源码打包并且把注释打成Javadoc交给客户,Eclipse或者MyEclipse自动打成的Javadoc文档都是基于网页格式的,打开是很方便,不过真的用的...

利用javadoc生成API文档

利用javadoc生成API文档参考文献:《疯狂Java讲义》
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:javadoc的写作
举报原因:
原因补充:

(最多只允许输入30个字)