- 浏览: 83964 次
- 性别:
- 来自: 长沙
最新评论
-
harbey:
文章写得非常的好,很有条理。如果能把图的内容讲得更详细就更好了 ...
再谈应用环境下的TIME_WAIT和CLOSE_WAIT -
wximeng:
好文,学习了
再谈应用环境下的TIME_WAIT和CLOSE_WAIT -
herojay2013:
<Context reloadable="tr ...
tomcat集群环境下,JSP页面更新同步,页面展示未更新 的问题排查 -
lakemove:
TOMCAT限制了"SHUTDOWN"命令 ...
由Tomcat 8005端口想到的...
JAVADOC语法
我们在开发JAVA程序中, 可以使用Javadoc来进行程序文档的整理, 当程序编写完成, 利用Java自带的JavaDoc工具就可以生成规范的API说明手册. 下面是我自己整理的一些语法:
书写格式:
/** <- 这里一定要用两个星号, 否则会被认为是普通注释的
* ........
*/
public int getCount() { .......
Javadoc只能为public,protected两种权限的类成员进行处理注释文档。当然也可以使用-private参数强制进行处理, 我们可以在注释中嵌入HTML个标记来丰富最后文档的显示, 因为Javadoc最后生成的文档就是HTML.
/**
* 一些参数列表<p>
*
* @see 类名
* @see 完整类名
* @see 完整类名#方法
*
* @param 参数名 说明
* @return 说明
* @exception 完整类名 说明
* @deprecated
*
* @version 版本信息
* @author 作者名
*/
说明:
@see : 就是文档中的 参见xx 的条目, 其实就是超链接.
一般来说, 文档有三种类型: 类注释, 变量注释, 方法注释, 这三中类型的注释除了都可以包含 @see 参数外, 其它所包含的参数是不同的.
1. 类注释
类注释是写在类前面的, 用来说明类的一些情况, 可以包涵 @version,@author参数, 但Javadoc缺省情况下不处理, 也就是说不在最后文档中出现的, 为了使用这些信息, 我们可以加入参数 -version和 -author来强制输出到最后的文档中.
2. 变量注释
变量注释写在变量前面, 只能包含 @see 参数
3. 方法注释
方法注释可以包括
@param : 参数名是指参数列表内的标识符, 说明就是一些解释性质的文字, 可以多行.
@return : 返回值的说明, 可以多行
@exception : 完整类名应该明确指定一个违例类的名字,它是在其它某个地方定义好的。而说明则阐述为什么这种特殊类型的违例会在方法调用中出现。说明可以多行
@deprecated : 指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能,因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated,则使用该方法时会收到编译器的警告。
javadoc的命令行语法如下:
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
参数可以按照任意顺序排列。下面分别就这些参数和相关的一些内容进行说明:
? Packagenames 包列表。这个选项可以是一系列的包名(用空格隔开),例如java.lang java.lang.reflect java.awt。不过,因为javadoc不递归作用于子包,不允许对包名使用通配符;所以你必须显示地列出希望建立文档的每一个包。
? Sourcefiles 源文件列表。这个选项可以是一系列的源文件名(用空格隔开),可以使用通配符。javadoc允许四种源文件:类源代码文件、包描述文件、总体概述文件、其他杂文件。
◇ 类源代码文件:类或者接口的源代码文件。
◇ 包描述文件:每一个包都可以有自己的包描述文件。包描述文件的名称必须是"package.html",与包的.java文件放置在一起。包描述文件的内容通常是使用HTML标记写的文档。javadoc执行时将自动寻找包描述文件。如果找到,javadoc将首先对描述文件中<body></body>之间的内容进行处理,然后把处理结果放到该包的Package Summary页面中,最后把包描述文件的第一句(紧靠<body>)放到输出的Overview summary页面中,并在语句前面加上该包的包名。
◇ 总体概述文件:javadoc可以创建一个总体概述文件描述整个应用或者所有包。总体概述文件可以被任意命名,也可以放置到任意位置。-overview选项可以指示总体概述文件的路径和名称。总体概述文件的内容是使用HTML标记写的文档。javadoc在执行的时候,如果发现-overview选项,那么它将首先对文件中<body></body>之间的内容进行处理;然后把处理后的结果放到输出的Overview summary 页面的底部;最后把总体概述文件中的第一句放到输出的Overview summary页面的顶部。
◇ 其他杂文件:这些文件通常是指与javadoc输出的HTML文件相关的一些图片文件、Java源代码文件(.java)、Java程序(.class)、Java小程序(Applets)、HTML文件。这些文件必须放在doc-files目录中。每一个包都可以有自己的doc-files目录。举个例子,你希望在java.awt.Button的HTML文档中使用一幅按钮的图片(Button.gif)。首先,你必须把图片文件放到C:usersrcjavaawtdoc-files中;然后在Button.java文件中加入下面注释
/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/
? @files 包含文件。为了简化javadoc命令,你可以把需要建立文档的文件名和包名放在一个或多个文本文件中。例如,为了简化下面命令:
javadoc -d apidoc com.mypackage1 com.mypackage2 com.mypackage3
你可以建立一个名称为mypackage.txt的文件,其内容如下:
com.mypackage1
com.mypackage2
com.mypackage3
然后执行下面命令即可:
javadoc -d apidoc @mypackage.txt
? options 命令行选项。javadoc使用doclets(doclets是指用doclet API编写的程序。)来确定输出的内容和格式。命令行选项中一部分是可用于所有doclet的通用选项,一部分是由默认的标准doclet提供的专用的选项。下面对各自一些常用的选项分别进行介绍:
通用选项:
◇ -1.1 生成具有javadoc 1.1版本生成的文档的外观和功能的文档。不是所有的选项都可以用于-1.1选项,具体可以使用javadoc -1.1 -help察看。
◇ -help 显示联机帮助。
◇ -bootclasspath classpathlist 指定"根类"(通常是Java平台自带的一些类。例如java.awt.*等)的路径。
◇ -sourcepath sourcepathlist 指定包的源文件搜索路径。但是必须注意,只有在javadoc命令中指定了包名的时候才可以使用-sourcepath选项。如果指定了包名,而省略了-sourcepath,那么javadoc使用类路径查找源文件。举例说明:假定你打算为com.mypackage建立文档,其源文件的位置是C:usersrc。那么你可以使用下面的命令:
javadoc -sourcepath c:usersrc com.mypackage
◇ -classpath classpathlist 指定javadoc查找"引用类"的路径。引用类是指带文档的类加上它们引用的任何类。javadoc将搜索指定路径的所有子目录。Classpathlist可以包含多个路径(使用;隔开)。如果省略-classpath,则javadoc使用-sourcepath查找源文件和类文件。举例说明:假定你打算为com.mypackage建立文档,其源文件的位置是C:usersrc,包依赖C:userlib中的库。那么你可以使用下面的命令:
javadoc -classpath c:userlib -sourcepath c:usersrc com.mypackage
◇ -overview pathfilename 告诉javadoc从pathfilename所指定的文件中获取概述文档,并且把它放到输出的概述页面(overview-summary.html)中。其中pathfilename是相对于-sourcepath的相对路径。
◇ -public 只显示公共类以及成员。
◇ -protected 只显示受保护的和公共的类以及成员。缺省选项。
◇ -package只显示包、受保护的和公共的类以及成员。
◇ -private 显示所有类和成员。
◇ -doclet class 指定javadoc产生输出内容的自定义doclet类。如果忽略这个选项,javadoc将使用默认的doclet产生一系列HTML文档。
◇ -docletpath classpathlist 与- doclet选项相关,制定自定义的doclet类文件的路径。Classpathlist可以包含多条路径(用;隔开)。
◇ -verbose 在javadoc运行时提供更详细的信息。
标准doclet专用选项:
◇ -author 在生成的文档中包含"作者"项。
◇ - d directory 指定javadoc保存生成的HTML文件的目录。省略该选项将把文件保存在当前目录。Directory可以是绝对目录,也可以是相对当前目录的相对目录。
◇ -version 在生成的文档中包含"版本"项。
◇ -use 为类和包生成"use"(用法)页面。这些页面描述了该类和包在javadoc命令涉及的文件中被使用的情况。例如:对于给定的类C,在C的用法页面中将包含C的子类,类型为C的域,返回变量类型为C的方法以及在参数中有变量类型为C的方法和构造器。
◇ -splitindex 把索引文件按照字母顺序分为多个文件。每一个文件对应一个字母。
◇ -windowtitle title 指定输出的HTML文档的标题。
◇ -header header 指定输出的HTML文档的页眉文本。
◇ -footer footer 指定输出的HTML文档的脚注文本。
◇ -bottom text 指定输出的HTML文档底部的文本。
◇ - group groupheading packagepatten;packagepatten;… 在总体概述页面中按照命令的指定方式分隔各个包。例如执行下面命令:
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
在页面中将有如下结果:
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new
◇ - noindex 不输出索引文件。
◇ - help 在文件的导航条中忽略help链接。
◇ - helpfile pathfilename 指定导航条中的help链接所指向的帮助文件。忽略该选项,javadoc将生成缺省的帮助文件。
◇ -stylesheetfile pathfilename 指定javadoc的HTML样式表文件的路径。忽略该选项,javadoc将自动产生一个样式表文件stylesheet.css。
JavaDoc文档标记
javadoc注释以"/**"开始,以"*/"结束,里面可以包含普通文本、HTML标记和javadoc标记。javadoc只处理源文件中在类/接口定义、方法、域、构造器之前的注释,忽略位于其他地方的注释。举例如下:
/**
*Demo--<b>Helloworld</b>
*@author sunjl
*@version 1.0 2001/10/15
*/
public class myHelloworld
{
/**
*在main( )方法中使用的显示用字符串
*@see #main(java.lang.String[])
*/
static String SDisplay;
/**
*显示HelloWorld
*@param args 从命令行中带入的字符串
*@return 无
*/
public static void main(String args[])
{
SDisplay = "Hello World " ;
System.out.println( SDisplay );
}
}
使用下面命令:
javadoc -private -d doc -author -version myHelloworld.java
即可以生成漂亮的关于myHelloworld.java的API文档了。
上面例子中以@开头的标记就是javadoc标记。在Java程序中正确使用javadoc标记是一个良好的注释习惯,将非常有助于javadoc自动从源代码文件生成完整的格式化API文档。下面就对各种标记进行详细说明。
◇ @author name-text 指定生成文档中的"作者"项,从JDK/SDK 1.0开始引入。name-text可以指定多个名字(使用","隔开)。文档注释可以包含多个类。
◇ {@docroot} 代表产生文档的根路径,从JDK/SDK 1.3开始引入。用法举例如下
/**
*see the <a href={@docroot}/copyright.html>copyright</a>
*/
假定生成文档的根目录是doc,上面注释所在的文件最后生成的文件是docutilityutl.html,那么"copyright"的链接会指向..copyright.html。
◇ @deprecated deprecated-text 添加注释,表明不推荐使用该API。
◇ @exception class-name description @throw的同义标记,从JDK/SDK 1.0开始引入。
◇ {@link package.class#member label} 插入指向package.class#member的内嵌链接,从JDK/SDK 1.2开始引入。举例说明,假定注释中有如下文档:
/** Use the {@link #getComponentAt(int, int) getComponentAt} method. */
那么javadoc最终生成的HTML页面中将有如下内容
Use the <a href = "Component.html#getComponentAt(int,int)" > getComponentAt </a> method.
◇ @param parameter-name description 描述参数,从JDK/SDK 1.0开始引入。
◇ @return description 描述返回值,从JDK/SDK 1.0开始引入。
◇ @see reference 添加"参见"标题,其中有指向reference的链接或者文本项,从JDK/SDK 1.0开始引入。@see标记有三种形式,下面分别说明:
(1)、@see "string" 为"string"添加文本项,不产生链接。
(2)、@see <a href="URL#Value">Label</a> _fcksavedurl=""URL#Value">Label</a>" 使用HTML标记产生链接
(3)、@see package.class#member Label 使用Java语言的名字package.class #member产生链接。
◇ @serial field-description 用于缺省可序列化域的注释,从JDK/SDK 1.2开始引入。
◇ @serialField field-name field-type field-description 建立Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档,从JDK/SDK 1.2开始引入。
◇ @serialData data-description data-description建立数据序列和类型的文档,从JDK/SDK 1.2开始引入。
◇ @since since-text 利用since-text内容为文档增加"since"标题,从JDK/SDK 1.1开始引入。
◇ @throws class-name description 与@exception同义。用class-name和description为输出文档添加"抛出"标题,从JDK/SDK 1.2开始引入。
◇ @version version-text 添加"版权"标题,从JDK/SDK 1.0开始引入。
上面介绍了标准doclet提供的所有标记。不过,需要注意这些标记的使用是有位置限制的。其中可以出现在类或者接口文档注释中的标记有:@see、{@link}、@since、@deprecated、@author、@version。可以出现在方法或者构造器文档注释中的标记有:@see、{@link}、@since、@deprecated、@param、@return、@throws、@exception、@serialData。可以出现在域文档注释中的有:@see、{@link}、@since、@desprecated、@serial、@serialField。
除了javadoc自身提供的标准标记以外,我们可以定制自己的标记吗?当然可以。只需要对javadoc标准的doclet程序进行扩充即可。实际上,利用javadoc提供的doclet API,不仅可以扩充doclet标记,甚至还可以改变javadoc的整个输出。为了满足需要,你可以使javadoc输出普通文本、XML文件等。由于扩充doclet涉及到Java编程,本文不再做深入介绍。
总之,javadoc提供了完整规范的API文档功能。在软件项目管理中,合理地使用javadoc不仅可以减少开发时的文档工作量,提高效率;而且还非常有利于将来软件的修改和维护。
JavaDoc 书写规范:
1、 File Header Comments : 每个文件都应该加上文件头标记,包括文件名、修改历史、版权信息和附加信息。例如:
/**
* @(#)demo.java 1.00 2002/05/27
*
* Copyright (c) 2000-2002 中国平安保险股份有限公司 版权所有
* Ping An Insurance Company of China. All rights reserved.
* This software is the confidential and proprietary
* information of Ping An Insurance Company of China.
* ("Confidential Information"). You shall not disclose
* such Confidential Information and shall use it only
* in accordance with the terms of the contract agreement
* you entered into with Ping An.
*/
2、class description:类信息,概括的描述类的功能和实现。
/** class description
*/
3、Variable Description:描述变量的意义和取值含义。
/** var variable description
*/
4、Method Description:标明每个方法的输入、输出参数和返回值类型,说明特殊变量取值的含义。相关类文档链接。
/** method description
* @param var signification
* @exception exception class name
* @return return_value return signification
*/
5、Association Description:关联类文档描述,在注释当中需要参引其它文档描述的地方,可在相应的注释当中如下插入:
/** method description
* @param var signification
* @exception exception class name
* @return return_value return signification
* @see package.class#member label
*/
6、包描述文件:概括描述包的功能和设计概要。为每个包创建一个描述文件,命名为package.html,与包的java文件放在一起。
注:javadoc生成文档时,会将该html文件的第一句放在package summary中,而把整个内容放在Overview summary中.
发表评论
-
HttpClient4.X 升级 入门 + http连接池使用
2011-05-12 17:09 4045转载请注明出处,谢谢~ http://blog.csdn.n ... -
HttpClient4.X 升级 入门 + http连接池使用
2011-05-12 17:09 0<p style="text-align: c ... -
JavaDoc 书写规范
2008-08-04 09:03 924在Java程序中正确使用javadoc标记是一个 ... -
Java 整数类型的使用和运算
2009-02-22 11:35 981Java 的数据分为对象(引用)类型和基本(简单)类型。 基 ... -
static函数使用
2009-02-27 18:40 887首先请看一个错误的例子: public class P38 ... -
assert关键字的使用
2009-02-27 19:56 1124在Java中,assert关键字是从JAVA SE 1.4 引 ... -
循环label使用
2009-02-28 13:52 1003循环的label(标记)跟臭名昭著的goto有点相似,java ... -
finalize()方法
2009-02-28 14:17 1136以下转自:孙卫琴《Java面向对象编程 》 11.4. ... -
不需要import的几种情况
2009-02-28 14:36 8561.java.lang 包 提供利用 Java 编程语言进行 ... -
Java clone() 影子克隆与深度克隆
2009-02-28 14:46 937以下文字转自:桔子园 http://www.blogjava. ... -
Javadoc 导出中文乱码解决
2009-04-24 21:08 1063在eclipse里面,project->Generate ... -
LinkedHashMap实现一个固定容量的基于最近最少使用算法的缓存类
2009-04-24 21:15 1379固定容量的基于最近最少使用算法的LinkedHashMap.可 ... -
Tomcat 自动加载
2009-05-09 16:40 1066遇到的问题是,在已部署的项目中添加一个新的Jar包,需要重启T ... -
M2Eclipse:Maven Eclipse插件无法搜索远程库的解决方法
2010-01-27 17:29 1488使用Eclipse安装了maven插件之后,创建Maven工程 ... -
由Tomcat 8005端口想到的...
2010-11-12 18:49 5493在阅读“tomcat启动分析” 的时候注意到server.xm ...
相关推荐
通过使用 JDK 提供的 javadoc.exe 工具,可以生成帮助文档,并备注了代码,可以参考注释的书写格式。今天,我们将详细介绍 javadoc 帮助文档的生成过程。 为什么需要生成帮助文档 在 Java 开发中,代码的可读性...
总的来说,jadetex是将Java源代码集成到LaTeX文档的实用工具,尤其适用于学术和技术写作。通过深入研究jadetex的源代码,开发者可以学习到如何将一种编程语言的语法解析与LaTeX排版系统相结合,这对于扩展其他语言的...
编译Java程序通常使用javac命令,运行则使用java命令,如果需要生成API文档,可以使用javadoc命令。 环境变量如JAVA_HOME、PATH和CLASSPATH对于Java开发至关重要。JAVA_HOME指向JDK的安装目录,PATH应包含%JAVA_...
- **6.4.2 JavaDoc命令的使用**:提供JavaDoc命令行工具的使用方法。 #### 6.5 参考资料 - 列出参考文献和相关资源,供读者进一步学习。 通过以上的详细介绍,我们可以看出Java编码规范对于提高代码质量和可维护性...
2. 代码注释的书写:文档中提到了javadoc,这是一种生成API文档的注释格式。 3. 代码的组织和模块化:如使用import语句导入其他类和包,以及使用package语句组织类和接口。 4. 代码的可读性:例如使用适当的缩进和...
3 书写格式规范 41 4 设计规范 44 4.1 质量测定基准(Metrics)规范 44 4.2 Class设计规范 44 4.3 Method设计规范 46 4.4 变量设计规范 47 5 Java语言规范 49 5.1 Object整体规范 49 5.2 修饰符规范 51 5.3 Javadoc...
- **(D) 都能支持**:错误选项,仅**(C)**能被javadoc命令识别。 ### 13. 线程休眠 - **知识点概述**:Java中的Thread类提供了控制线程执行的方法,如暂停线程。 - **选项解析**: - **(A) wait()**:Object类的...
".tar.gz"是一个常见的Unix/Linux档案格式,它通过tar命令将多个文件打包,并使用gzip进行压缩。用户需要先解压,然后编译安装Redis。 **知识点详解** 1. **JDK 15特性**:JDK 15引入了一些新功能,比如文本块...
8. **布尔型**(boolean):使用`Boolean`(注意首字母大写)表示,虽然在Java中通常写作`boolean`,但其对应的类是`Boolean`。布尔类型只有两个值:`true`和`false`,用于逻辑判断。 在计算机系统中,数据是以位...
- **javadoc 注释**: 支持 `javadoc` 命令的注释格式为 `/** ... */`。 #### 三、判断题知识点解析 - **Java 的特性**: Java 具有良好的安全性和可移植性,支持跨平台运行。 - **编译类型**: Java 采用编译解释型...
7. **其他改进和API**:包括更好的IPv6支持、新的`ProcessHandle` API以获取和控制进程信息、改进的Javadoc命令等。 在解压并安装"jdk-11.0.4_linux-x64_bin.tar.gz"后,你需要配置环境变量,以便系统能够识别和...
*/`形式,能够支持Javadoc命令生成文档。 #### 三、判断题解析 **1. Java 语言具有较好的安全性和可移植性及与平台无关等特性。(√ )** - **解析:** 正确,Java 的设计考虑了安全性、可移植性和与平台无关性...
- 使用JDK 11,开发者可以使用`javac`命令编译Java源代码,用`java`命令运行已编译的类,也可以通过`javadoc`生成文档。 - `java --version`可以验证JDK是否正确安装并查看版本信息。 总结,JDK 11.0.6 for ...
- **类的定义与对象实例化**:学习如何定义类,声明并实例化对象,以及如何区分和使用构造方法和实例方法。 - **汽车类设计**:创建一个汽车类,包含车牌号和价格属性,以及一个修改价格的方法。 - **银行账户类**:...
程序的书写规范包括类名、方法名和变量名的首字母大写和小写的约定,以及使用注释来提高代码的可读性。注释有三种形式:单行注释(`//`),多行注释(`/* ... */`)和文档注释(`/** ... */`),后者可以被`javadoc`...
使用`javadoc`命令可以从源代码中的文档注释自动生成HTML格式的文档。 #### 五、Java程序的运行过程 1. **启动JVM**: Java程序的运行始于JVM的启动。 2. **类的查找**: JVM会在`JAVA_HOME/jre/lib`目录下查找所...
- **安装与配置**:在计算机上安装JDK后,需要配置环境变量JAVA_HOME和Path,以便在任何目录下都能运行JDK的命令。 - **JDK组件**:包括javac(Java编译器)、java(Java解释器)、jar(Java归档工具)、javadoc...
- `jar`命令用于打包和压缩Java类文件到一个`.jar`归档文件,便于分发和执行。 2. **源文件结构**: - Java源文件的正确顺序应为:`package`声明(可选),`import`声明,然后是类或接口定义。正确顺序是`package...