JDK的bin目录下你可以找到javadoc(如果是Windows下的JDK,它的文件名为javadoc.exe).使用javdoc编译.java源文件时,它会读出.java源文件中的文档注释,并按照一定的规则与Java源程序一起进行编译,生成文档.
javadoc -d 文档存放目录 -author -version 源文件名.java
这条命令编译一个名为"源文件名.java"的java源文件,并将生成的文档存放在"文档存放目录"指定的目录下,生成的文档中index.html就是文档的首页.(-author和-version两个选项可以省略).
生成的文档是HTML格式,而这些HTML格式的标识符并不是javadoc加的,而是我们在写注释的时候写上去的.比如,需要换行时,不是敲入一个回车符,而是写入<br>,如果要分段,就应该在段前写入<p>.
因此,格式化文档,就是在文档注释中添加相应的HTML标识.
文档注释只能说明类,属性和方法.
文档注释的正文并不是直接复制到输出文件(文档的HTML文件),而是读取每一行后,删掉前导的*号及*号以前的空格,再输入到文档的.如
/**
*This is first line.<br>
***** This is second line.<br>
This is third line.
*/
编译输出后的HTML源码则是
This is first line.<br>
This is second line.<br>
This is third line.
允许连续使用多个*,效果和一个*一样,但多个*号前不能有其它字符分隔,否则分隔符及后面的*号都将作为文档的内容.
*号在这里作为左边界使用,如果没有前导的*号,则边界从第一个有效字符开始,而不包括前面的空格,如上例第三行.
文档注释只说明紧接其后的类,属性或者方法.
文档注释分为三部分:
/**
* show方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true表示显示,false表示隐藏* @return没有返回值
*/
public void show(boolean b){frame.show(b);}
javadoc标记由"@"及其后所跟的标记类型和专用注释引用组成.
标记 用于 作用
@author 对类的说明 标明开发该类模块的作者
@version 对类的说明 标明该类模块的版本
@see 对类,属性,方法的说明 参考转向,也就是相关主题
@param 对方法的说明 对方法中某参数的说明
@return 对方法的说明 对方法返回值的说明
@exception 对方法的说明 对方法可能抛出的异常进行说明
1.@see的使用
@see的句法有三种:
@see类名
@see#方法名或属性名
@see类名#方法名或属性名
如果java源文件中的import语句包含了的类,可以只写出类名,如果没有包含,则需要写出类全名.
java.lang也已经默认被包含了.这和javac编译java源文件时的规定一样,所以可以简单的用javac编译来判断,源程序中javac能找到的,javadoc 也一定能找到.javac找不到的类,javadoc也找不到,这就需要使用类全名了.
如果是属性名,则只需要写出属性名即可.
如果是方法名,则需要写出方法名以及参数类型,没有参数的方法,需要写出一对括号.
成员类型 成员名称及参数 @see句法
属性 number @see number
属性 count @see count
方法 count() @see count()
方法 show(boolean b) @see show(boolean)
方法 main(String[] args) @see main(String[])
没有指出类名,则默认为当前类.所以它定义的参考,都转向本类中的属性或者方法.而第三个句法中指出了类名,则还可以转向其它类的属性或者方法.
关于@see标记,我们举个例说明.由于@see在对类说明,对属性说明,对方法说明时用法都一样,所以这里只以对类说明为例.
/**
* @see String
* @see java.lang.StringBuffer
* @see #str
* @see #str()
* @see #main(String[])
* @see Object#toString()*/
public class TestJavaDoc{}
String和StringBuffer都是在java.lang包中,由于这个包是默认导入了的,所以这两个类可以直接写类名,也可以写类全名.str,str()为同名属性和方法,所以方法名需要用()区分.main是带参数的方法,所以在()中指明了参数类型.toString()虽然在本类中也有(从Object继承的),但我们是想参考Object类的toString()方法,所以使用了Object#toString().
为什么其中只有str,str()和main(String[])变成了链接呢?
那是因为编译时没有把java.lang包或者Stirng,StringBuffer,Object三个类的源文件一起加入编译,所以,生成的文档没有关于那三个类的信息,也就不可以建立链接了.
上例中如果去把类中的str属性去掉,那么生成的文档又会有什么变化呢?
你会发现,原来是str,str(),而现在变成了str(),str(),因为str属性已经没有了,所以str也表示方法str().
2.使用@author,@version说明类
这两个标记分别用于指明类的作者和版本.缺省情况下javadoc将其忽略,但命令行开关-author和-version可以修改这个功能,使其包含的信息被输出.这两个标记的句法如下:
@author 作者名
@version 版本号
@author可以多次使用,以指明多个作者,生成的文档中每个作者之间使用逗号(,)隔开.
@version也可以使用多次,只有第一次有效,生成的文档中只会显示第一次使用@version指明的版本号.
/**
* @author Fancy
* @author Bird
* @version Version 1.00
* @version Version 2.00
*/
public class TestJavaDoc{}
可以将上述两条@author语句合为一句,把两个@version语句也合为一句:
@author Fancy<br>Bird
@version Version 1.00<br>Version 2.00
使用@param,@return和@exception说明方法
这三个标记都是只用于方法的.
@param描述方法的参数
@return 描述方法的返回值
@exception 描述方法可能抛出的异常.
@param 参数名 参数说明
@return 返回值说明
@exception 异常类名 说明
每一个@param只能描述方法的一个参数,所以,如果方法需要多个参数,就需要多次使用@param来描述.
一个方法中只能用一个@return,如果文档说明中列了多个@return,则javadoc编译时会发出警告,且只有第一个@return在生成的文档中有效.
方法可能抛出的异常应当用@exception描述.由于一个方法可能抛出多个异常,所以可以有多个@exception.每个@exception后面应有简述的异常类名,说明中应指出抛出异常的原因.需要注意的是,异常类名应该根据源文件的import语句确定是写出类名还是类全名.
public class TestJavaDoc{
/**
* @param n a switch
* @param b excrescent parameter
* @return true or false* @return excrescent return
* @exception java.lang.Exception throw when switch is 1
* @exception NullPointerException throw when parameter n is null
*/
public boolean fun(Integer n) throws Exception {
switch(n.intValue()){
case 0:
break;
case 1:
throw new Exception("Test Only");
default: return false;}return true;}}
运行: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编译文档时可以给定包列表,也可以给出源程序文件列表.例如在 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选项,则必须指定标题文本.
相关推荐
这份文档详细说明了myEclipse/Eclipse中是如何配置java文档注释的,每次在myEclipse/Eclipse中写java代码时就可以用同一的文档注释了,减少了手工注释的麻烦。
一个好的程序员工资的体现不仅仅在于技术的强弱,还体现在注释的书写上
这个是java文档注释模板,使用myeclipse创建的,里面添加了基本颜色,只需导进到开发工具就可以了
java注释全解,内容全面,包括hibernate注解、Java注解、Spring注解、SSH全注解等内容,分为4个文档介绍。另附一些精品java学习资料,欢迎大家下载学习。
具体内容可参阅主页文章:【2023,学点儿新Java-09】Java初学者常会犯的错误总结与解决方案 | Java中的注释类型 | 详细教学:通过命令行 执行 Java中特有的文档注释
eclipse中java类注释模板,有需要的朋友可以参考使用。
java编码规范及注释快捷键.doc
Java-文档注释例子
有关于java的注释规范的详细描述,单行注释、多行注释、分块注释等这些java的三种注释方式
赠送jar包:javacv-1.5.7.jar; 赠送原API文档:javacv-1.5.7-javadoc.jar; 赠送源代码:javacv-1.5.7-sources.jar;...人性化翻译,文档中的代码和结构保持不变,注释和说明精准翻译,请放心使用。
Java注释的良好习惯,方便项目的交接和事后的维护与整理,是一个很好的帮助自己养成编码习惯的工具,效果图在我的博文有记录,有需要的伙伴可以自行下载哦~
本专栏主要为Java程序设计(基础)实验报告和Java程序设计(进阶)实验报告,基础篇有JAVA环境搭建、Java语言基础、方法和数组、面向对象基础、Java常用类、继承与接口、成员访问控制与异常、JavaFX程序设计、Java...
赠送jar包:javacv-1.5.5.jar; 赠送原API文档:javacv-1.5.5-javadoc.jar; 赠送源代码:javacv-1.5.5-sources.jar;...人性化翻译,文档中的代码和结构保持不变,注释和说明精准翻译,请放心使用。
Java 文档注释 Java 支持三种注释方式。前两种分别是 // 和 /* */,第三种被称作说明注释,它以 /** 开始,以 */结束。 说明注释允许你在程序中嵌入关于程序的信息。你可以使用 javadoc 工具软件来生成信息,并输出...
后端开发技术的代码注释规范 单行注释 多行注释 块注释 文档注释 标签注释等等
本文档是 Java 2 Platform Standard Edition 6.0 的 API 规范。 请参见: 描述 Java 2 Platform 软件包 java.applet 提供创建 applet 所必需的类和 applet 用来与其 applet 上下文通信的类。 java.awt 包含...
Java Annotation注解技术
java程序注释的规范,每个初学者都应该掌握规范进行编程开发和学习,习惯了规范,自然就会提升代码的质量,提升团队的开发进度!
赠送jar包:javacv-1.5.7.jar; 赠送原API文档:javacv-1.5.7-javadoc.jar; 赠送源代码:javacv-1.5.7-...人性化翻译,文档中的代码和结构保持不变,注释和说明精准翻译,请放心使用。 双语对照,边学技术、边学英语。
赠送jar包:javacv-1.5.5.jar; 赠送原API文档:javacv-1.5.5-javadoc.jar; 赠送源代码:javacv-1.5.5-...人性化翻译,文档中的代码和结构保持不变,注释和说明精准翻译,请放心使用。 双语对照,边学技术、边学英语。