- 浏览: 37566 次
文章分类
- 全部博客 (37)
- java (37)
- [文摘20081112]经典语录 (1)
- php+mysql预查询prepare 与普通查询的性能对比 (1)
- Android采用SharedPreferences保存用户登录信息 (1)
- 找bug记(2) (1)
- 细节优化提升资源利用率 (1)
- java(j2se)学习笔记----类注释文档编写方法? (1)
- 如何查看Class文件编译的JDK版本 (1)
- 验证码显示不了,报Could not initialize class sun.awt.X11GraphicsEnvironment (1)
- Android使用KSOAP2调用WebService及正确导入jar包的问题 (1)
- The content of the adapter has changed but ListView did not receive a notification. (1)
- 很想写些CMMI的东西 (1)
- JPA & Hibernate 注解 (1)
- Java反编译工具――Jode (1)
- Eclipse3.0.0插件安装解决方法 (1)
- SVG简介及相关工具 (1)
- 开始在这个BLOG里放一部分MapXtreme2004相关代码 (1)
- 支持.NET环境的GIS开发工具MapXtreme2004 (1)
- 将DAT格式视频文件转换成ASF和WMV格式视频文件 (1)
- 《漫谈设计模式》一书终于出版了 (1)
- 一位程序员的一个LBS应用的想法 (1)
- 一刷网络投票的小程序 (1)
- 面试字符串处理之单词翻转 (1)
- rails 上载xls文件 (1)
- 如何获得Java项目文件所在的相对路径 (1)
- 学习FlexViewer(一)——事件和框架 (1)
- Android开发之消息处理机制(二)——消息循环 (1)
- JAVA操作——获取文件扩展名,去掉文件扩展名 (1)
- freemarker 读取session 值 (1)
- xfire 使用用户名/密码进行身份认证 (1)
- java中的图片处理 (1)
- HTC Touch HD2/LEO/T8585刷机教程 进三色屏 (1)
- js性能问题 (1)
- js 事件收集 (1)
最新评论
-
Glorin:
非常感谢你,让我的问题能够得以解决。
验证码显示不了,报Could not initialize class sun.awt.X11GraphicsEnvironment -
thzthbthy:
/*
* Java文件操作 获取文件扩展名
*
...
JAVA操作——获取文件扩展名,去掉文件扩展名 -
jyjava:
你debug调试,应该很快会定位到的
找bug记(2) -
xuehua1987:
上面的方法返回值是void ,怎么可以返回你取到的连接???? ...
找bug记(2)
java(j2se)学习笔记----类注释文档编写方法?
对于Java语言,最体贴的一项设计就是它并没有打算让人们为了写程序而写程序——人们也需要考虑程序的文档化问题。对于程序的文档化,最大的问题莫过于对文档的维护。若文档与代码分离,那么每次改变代码后都要改 <br>
变文档,这无疑会变成相当麻烦的一件事情。
解决的方法看起来似乎很简单:将代码同文档“链接”起来。为达到这个目的,最简单的方法是将所有内容都置于同一个文件。然而,为使一切都整齐划一,还必须使用一种特殊的注释语法,以便标记出特殊的文档;另外还需要一个工具,用于提取这些注释,并按有价值的形式将其展现出来。这些都是Java必须做到的。
用于提取注释的工具叫作javadoc。它采用了部分来自Java编译器的技术,查找我们置入程序的特殊注释标记。它不仅提取由这些标记指示的信息,也将毗邻注释的类名或方法名提取出来。这样一来,我们就可用最轻的工作量,生成十分专业的程序文档。
javadoc输出的是一个HTML文件,可用自己的Web浏览器查看。该工具允许我们创建和管理单个源文件,并生动生成有用的文档。由于有了jvadoc,所以我们能够用标准的方法创建文档。而且由于它非常方便,所以我们能轻松获得所有Java库的文档。
1具体语法
所有javadoc命令都只能出现于“/**”注释中。但和平常一样,注释结束于一个“*/”。主要通过两种方式来使用javadoc:嵌入的HTML,或使用“文档标记”。其中,“文档标记”(Doc tags)是一些以“@”开头的命令,置于注释行的起始处(但前导的“*”会被忽略)。
有三种类型的注释文档,它们对应于位于注释后面的元素:类、变量或者方法。也就是说,一个类注释正好位于一个类定义之前;变量注释正好位于变量定义之前;而一个方法定义正好位于一个方法定义的前面。如下面这个简单的例子所示:
/** 一个类注释 */
public class docTest {
/** 一个变量注释 */
public int i;
/** 一个方法注释 */
public void f() {}
}<br>
注意javadoc只能为public(公共)和protected(受保护)成员处理注释文档。“private”(私有)和“友好”(详见5章)成员的注释会被忽略,我们看不到任何输出(也可以用-private标记包括private成员)。这样做是有道理的,因为只有public和protected成员才可在文件之外使用,这是客户程序员的希望。然而,所有类注释都会包含到输出结果里。
上述代码的输出是一个HTML文件,它与其他Java文档具有相同的标准格式。因此,用户会非常熟悉这种格式,可在您设计的类中方便地“漫游”。设计程序时,请务必考虑输入上述代码,用javadoc处理一下,观看最终HTML文件的效果如何。
2嵌入HTML
javadoc将HTML命令传递给最终生成的HTML文档。这便使我们能够充分利用HTML的巨大威力。当然,我们的最终动机是格式化代码,不是为了哗众取宠。下面列出一个例子:<br><br>
/**
*
* System.out.println(new Date());
*
*/
亦可象在其他Web文档里那样运用HTM <br>
L,对普通文本进行格式化,使其更具条理、更加美观:
/**
* 您甚至可以插入一个列表:
*
*
项目一
*
项目二
*
项目三
*
*/
注意在文档注释中,位于一行最开头的星号会被javadoc丢弃。同时丢弃的还有前导空格。javadoc会对所有内容进行格式化,使其与标准的文档外观相符。不要将
或这样的标题当作嵌入HTML使用,因为javadoc会插入自己的标题,我们给出的标题会与之冲撞。
所有类型的注释文档——类、变量和方法——都支持嵌入HTML。
3@see
:引用其他类
所有三种类型的注释文档都可包含@see标记,它允许我们引用其他类里的文档。对于这个标记,javadoc会生成相应的HTML,将其直接链接到其他文档。格式如下:
@see 类名
@see 完整类名
@see 完整类名
每一格式都会在生成的文档里自动加入一个超链接的“See Also”(参见)条目。注意javadoc不会检查我们指定的超链接,不会验证它们是否有效。
4类文档标记
随同嵌入HTML和@see引用,类文档还可以包括用于版本信息以及作者姓名的标记。类文档亦可用于“接口”目的(本书后面会详细解释)。
(1). @version
格式如下:
@version 版本信息
其中,“版本信息”代表任何适合作为版本说明的资料。若在javadoc命令行使用了“-version”标记,就会从生成的HTML文档里提取出版本信息。
(2). @author
<p class="newtext">@author 作者信息
ado
</span>
</a>
c命令行使用了“-<!-- 正文页网画中画广告 -->
<table style="margin: 10px 7px 3px 4px;" border="0" cellspacing="0" cellpadding="0" align="left"><tbody><tr>
<td>
<div id="ad_position_roller_35">
<!--
-->
</td>
</tr></tbody></table>
author”标记,就会专门从生成的HTML文档里提取出作者信息。
5变量文档标记
<p class="newtext">变量文档只能包括嵌入的HTML以及@see引用。
6方法文档标记
(1). @param
<p class="newtext">格式如下:
<p class="newtext">其中,“参数名”是指参数列表内的标识符,而“说明”代表一些可延续到后续行内的说明文字。一旦遇到一个新文档标记,就认为前一个说明结束。可使用任意数量的说明,每个参数一个。
(2). @return
<p class="newtext">@return 说明
(3). @exception
<p class="newtext">有关“违例”(Exception)的详细情况,我们会在第9章讲述。简言之,它们是一些特殊的对象,若某个方法失败,就可将它们“扔出”对象。调用一个方法时,尽管只有一个违例对象出现,但一些特殊的方法也许能产生任意数量的、不同类型的违例。所有这些违例都需要说明。所以,违例标记的格式如下:
<p class="newtext">其中,“完整类名”明确指定了一个违例类的名字,它是在其他某个地方定义好的。而“说明”(同样可以延续到下面的行)告诉我们为什么这种特殊类型的违例会在方法调用中出现。
(4). @depre<a href="http://topic.ccw.com.cn/corpCenter/249.html" target="_blank"><span style="color: #0000cc;">ca
</span>
</a>
ted
这是Java 1.1的新特性。该标记用于指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能,因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated,则使用该方法时会收到编译器的警告。
发表评论
-
js 事件收集
2012-02-08 13:18 512一般事件 事件 浏 ... -
js性能问题
2012-02-08 13:13 724随着web应用的复杂度日渐提高,JavaScript代 ... -
HTC Touch HD2/LEO/T8585刷机教程 进三色屏
2012-02-07 15:53 1017[size=14px; line-height: 21 ... -
java中的图片处理
2012-02-04 12:44 767附件中的文件包括: 1.图片的压缩 2.处理圆角图片 ... -
xfire 使用用户名/密码进行身份认证
2012-02-03 16:59 1121对SOAP报文进行身 ... -
freemarker 读取session 值
2012-02-03 08:25 2441<span style="font-f ... -
JAVA操作——获取文件扩展名,去掉文件扩展名
2012-01-31 14:08 2223<p> 昨天收邮件,得知要参加一个产品部的 ... -
Android开发之消息处理机制(二)——消息循环
2012-01-11 14:53 765<h1>Android开发 ... -
学习FlexViewer(一)——事件和框架
2012-01-11 11:44 1185????? 上午做了关于FlexViewer的讲座,项 ... -
如何获得Java项目文件所在的相对路径
2011-12-28 15:08 2259[size=18px;]今天在开发中做一个java项 ... -
rails 上载xls文件
2011-12-21 12:14 1065?<span style="font- ... -
面试字符串处理之单词翻转
2011-12-21 11:34 843<p align="left&quo ... -
一刷网络投票的小程序
2011-12-20 11:44 1218最近看到网上一投 ... -
一位程序员的一个LBS应用的想法
2011-12-20 10:14 684最近状态不佳, ... -
《漫谈设计模式》一书终于出版了
2011-12-19 13:09 883<p class="MsoNor ... -
将DAT格式视频文件转换成ASF和WMV格式视频文件
2011-12-17 15:29 854以*.ASF和*.WMV为后缀名的视频文件,是微软针对 ... -
支持.NET环境的GIS开发工具MapXtreme2004
2011-12-16 16:12 675<font color="#ff000 ... -
开始在这个BLOG里放一部分MapXtreme2004相关代码
2011-12-15 14:38 527MapXtreme2004是嵌入到.NET环境中的地理 ... -
SVG简介及相关工具
2011-12-14 15:47 662<span style="" ... -
Eclipse3.0.0插件安装解决方法
2011-12-14 15:27 718<p class="MsoNorma ...
相关推荐
Java-J2SE学习笔记Java-J2SE学习笔记Java-J2SE学习笔记Java-J2SE学习笔记Java-J2SE学习笔记Java-J2SE学习笔记Java-J2SE学习笔记Java-J2SE学习笔记
本书内容非常全面,涵盖了《Java编程思想》、《Java学习笔记》等书籍所有知识要点,并结合作者自己经验总结而编写,内容丰富程度胜过一切书籍 众所周知,一般书籍为了销售需要,往往很少的知识点,却需要添加大量的...
Java-J2SE学习笔记
j2se-doc-cn java的API文档,有助于你写JAVA程序.希望大家更加踊跃的学习和更好的学习JAVA。
自己的j2se学习笔记和收集的一部分笔记
j2se学习笔记.doc j2se学习笔记.doc j2se学习笔记.doc j2se学习笔记.doc
我的学习笔记 需要就下载吧 接口 上课时的课堂笔记及相关程序
Java Web ppt 开发 J2SE 学习笔记
资源名称:Java-J2se、J2ee开发全程视频教程和源码(87集)资源目录:【】Java-J2se-J2ee全程教程(01-10)【】Java-J2se-J2ee全程教程(11-20)【】Java-J2se-J2ee全程教程(21-30)【】Java-J2se-J2ee全程教程(31...
资源名称:【一脚揣进J2SE】视频教程(持续更新)资源目录:【】《一脚踹进J2SE》1-1Java简介【】《一脚踹进J2SE》1-2Java运行环境搭建【】《一脚踹进J2SE》1-3HelloWorld实现及Java运行原理介绍【】《一脚踹进J2SE...
J2SE学习实例 1、Java的基础知识 2、Java面向对象 3、集合Collection的使用 4、IO使用 5、Socket编程 6、Thread线程技术 7、Subject反射技术 8、GUI图形编程
java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记java笔记
java学习总结1 -- j2se 项目环境: jdk8 字符集:UTF-8 开发工具:Eclipse 包括内容: basic 基本语法 oop 面向对象 api 常用api及工具类 javadoc javaDoc的使用 debug 代码调试方法 datastructure 基本数据结构 ...
java学习中纪录的笔记,JAVA学习中不可多得的一个帮助文档或学习工具。
中文译名是J2SE参考大全(第5版) 这份是自己制作的电子书,现在还没有制作完成,因为内容太多,关打字就打个半死.