JAVA文档注释

JAVA注释类型

Java 注释分为三类

单行注释 //

多行注释/**/

文档注释/***/

单行注释多行注释主要用于代码辅助性的说明便于理解代码的逻辑

文档注释主要用生成API文档

文档注释类型

文档注释紧挨方法属性前面放置否则容易出错或不能在文档中输出

为是文档注释更加清晰注释中常用一些注解HTML格式标签

注解

1.常用注解

spacer.gifspacer.gif

2.方法常用注解

@since 1.2

@param方法参数类型可以出现多次

@return方法返回的值每个方法只能出现一次

@exception 方法肯能抛出的异常可以出现多次

在生成文档中显示样式如下图

 

属性常用注解

@since 1.2

在生成文档中显示样式如下图

spacer.gif

HTML 标签

文档注释中可以用HTML格式调整在生成的API文档中显示的格式

以JDKAPI 为例其中常见的一些格式有(合法的标签都可以用作显示)

<br>换行

<tt>表示方法<tt> 字体小一号显示“表示方法”

{@link #setStr(String)}“setStr(String)”可以有超链接的功能

重点讲解 @see

@see #str

 @see #str()

@see #setStr(java.lang.String)

@see #getStr() @see #main(String[])

@see Object#toString()

在文档中的显示格式为可以超链接到对应的方法和属性

 

有两种格式 @see Object#str#前面是类名(为空时默认为当前类)

#后面是属性名或方法名

@see #str既可以表示属性又可以表示方法优先级匹配属性– 匹配方法

@see #str()表示方法

类名称也可以用全路径名如 java.lang.Stringjava.lang.Object

是否使用使用全路径名准则:如果有Import语句则可以不用全路径名

了解更详细的参看http://www.yesky.com/323/218323_7.shtml

这是一个例子程序自己亲自动手生成HTML 文档更容易理解

/*

*javadoc -private -df:/wen -author -version f:/*.java

*生成的DOC存放路径java文件的路径

*javadoc -d f:/wen f:/*.java生成的文档不包含作者和版本信息

*<br><A HREF="http://www.yesky.com/323/218323_7.shtml" target="_blank">JavaDoc命令链接</A>

*/

/**

*

* This is My First Java Document

* <br>@see参见的属性或方法<br> Object#toString() 表示Object类中的方法{@link #setStr(String)}<br> #str 是本类中的属性

* <br>str() <tt>表示方法<tt>str 既可以表示属性也可以表示方法(首先在类中查找是否有对应的属性没有则查看是否有对应的方法)

* <br><A HREF="http://www.yesky.com/323/218323_7.shtml" target="_blank">JavaDoc命令链接</A>

* @see #str

* @see #str()

* @see #setStr(java.lang.String)

* @see #getStr()

* @see #main(String[])

* @see java.lang.Object#toString()

* @since 1.2 

* @author zhao xiaoming

* @version 1.0

*/

public class MyJavaDoc{

/**

* This properties public 

* @since 1.2

*<br>

* @since 1.3 

*/

public String str = null;

/**

* This properties private

* @since 1.2

* @since 1.3 

*/

public String strs = null;

/**

* This properties private

* @return 0

*/

public int str(){

return 0;

}

/**

* This method return the value of properties

* if you know this method

* @param String

* @return void

*/

public void setStr(String str){

this.str = str;

}

public String getStr(){

return this.str;

}

//<br>@param @return @exception 这三个标记只是用于描述方法

//其中@return 只能出现一次其它两个则可以多次出现

/**

* This Method is static <br> <p>Java Program is good<p> 

*@param String[]

*@return null

*@since 1.2 

*@exception java.lang.Exception throw when switch is 1

*@exception NullPointerException throw when parameter n is null

*/

public static void main(String[] args){

}

}

四. javadoc 命令

运行 javadoc -help 可以看到 javadoc 的用法,这里列举常用参数如下: 

用法:  

 javadoc [options] [packagenames] [sourcefiles]  

选项:

   -public 仅显示 public 类和成员
   -protected 显示 protected/public 类和成员 (缺省) 
   -package 显示 package/protected/public 类和成员
   -private 显示所有类和成员
   -d <directory输出文件的目标目录
   -version 包含 @version 
   -author 包含 @author 
   -splitindex 将索引分为每个字母对应一个文件
   -windowtitle <text文档的浏览器窗口标题

javadoc -private -df:/wen -author -version f:/*.java

javadoc 编译文档时可以给定包列表,也可以给出源程序文件列表。例如在 CLASSPATH 下有两个包若干类如下:  

fancy.Editor  

fancy.Test  

fancy.editor.ECommand  

fancy.editor.EDocument  

fancy.editor.EView  

这里有两个包 (fancy 和 fancy.editor) 和 5 个类。那么编译时 (Windows 环境) 可以使用如下 javadoc 命令:

javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java

这是给出 java 源文件作为编译参数的方法,注意命令中指出的是文件路径,应该根据实际情况改变。也可以是给出包名作为编译参数,如:

javadoc fancy fancy.editor  

用浏览器打开生成文档的 index.html 文件即可发现两种方式编译结果的不同,如下图:

spacer.gif


  用第二条命令生成的文档被框架分成了三部分:包列表、类列表和类说明。在包列表中选择了某个包之后,类列表中就会列出该包中的所有类;在类列表中选择了某个类之后,类说明部分就会显示出该类的详细文档。而用第一条命令生成的文档只有两部分,类列表和类说明,没有包列表。这就是两种方式生成文档的最大区别了。

  两种方式编译还有一点不同,

  下面再来细说选项。

  -public、-protected、-package、-private 四个选项,只需要任选其一即可。它们指定的显示类成员的程度。它们显示的成员多少是一个包含的关系,如下表:

  -private (显示所有类和成员) 
  -package (显示 package/protected/public 类和成员) 
  -protected (显示 protected/public 类和成员) 
  -public (仅显示 public 类和成员) 

  -d 选项允许你定义输出目录。如果不用 -d 定义输出目录,生成的文档文件会放在当前目录下。-d 选项的用法是

  -d 目录名

  目录名为必填项,也就是说,如果你使用了 -d 参数,就一定要为它指定一个目录。这个目录必须已经存在了,如果还不存在,请在运行 javadoc 之前创建该目录。

  -version 和 -author 用于控制生成文档时是否生成 @version 和 @author 指定的内容。不加这两个参数的情况下,生成的文档中不包含版本和作者信息。

  -splitindex 选项将索引分为每个字母对应一个文件。默认情况下,索引文件只有一个,且该文件中包含所有索引内容。当然生成文档内容不多的时候,这样做非常合适,但是,如果文档内容非常多的时候,这个索引文件将包含非常多的内容,显得过于庞大。使用 -splitindex 会把索引文件按各索引项的第一个字母进行分类,每个字母对应一个文件。这样,就减轻了一个索引文件的负担。

  -windowtitle 选项为文档指定一个标题,该标题会显示在窗口的标题栏上。如果不指定该标题,而默认的文档标题为“生成的文档(无标题)”。该选项的用法是:

  -windowtitle 标题

  标题是一串没有包含空格的文本,因为空格符是用于分隔各参数的,所以不能包含空格。同 -d 类似,如果指定了 -windowtitle 选项,则必须指定标题文本。