java 文件备注_JAVA 文档注释

JAVA文档注释

一JAVA注释类型

Java注释分为三类

1单行注释 //

2多行注释/**/

3文档注释/***/

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

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

二文档注释类型

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

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

注解

1.类常用注解

2.方法常用注解

@since 1.2

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

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

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

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

3属性常用注解

@since 1.2

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

HTML标签

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

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

换行

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

{@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文档更容易理解

/*

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

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

*JavaDoc命令链接

*/

/**

*

* This is My First Java Document

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

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

* JavaDoc命令链接

* @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

*

* @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;

}

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

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

/**

* This Method is static 

Java Program is good

*@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文件即可发现两种方式编译结果的不同，如下图：

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

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

下面再来细说选项。

-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选项，则必须指定标题文本。