Java 注释

本文详细介绍了Java中的注释类型及其用途,包括单行注释、多行注释和文档注释。特别关注文档注释的使用,如@throws、@param、@return等标签,并解释了如何使用javadoc工具自动生成文档。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

Java 注释

单行注释:// 注释内容

多行注释:/* … 注释内容….*/

文本注释:/* * .. 注释内容…. */


文本注释:/* * .. 注释内容…. */

文本注释能够自动地生成文档。在JDK中有个javadoc的工具 ( 用法: javadoc [options] [packagenames] [sourcefiles] [@files] ),可以由源文件生成一个HTML文档。使用这种方式注释源文件的内容:专业,快速、有效、便于修改并且能够源文件的保存而保存起来。当修改源文件时,也可能对这个源代码的需求等一些注释性的文字进行修改,那么,这时候可以将源代码和文档一同保存,而不用再另外创建一个文档。

文档注释位置

(1)类注释。类注释用于说明整个类的功能、特性等,它应该放在所有的“import”语句之后,在class定义之前。
这个规则也适用于接口(interface)注释。
(2)方法注释。方法注释用来说明方法的定义,比如,方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。
(3)属性注释。默认情况下,javadoc只对公有(public)属性和受保护属性(protected)产生文档——通常是静态常量。
(4)包注释。类、方法、属性的注释都直接放到Java的源文件中,而对于包的注释,无法放到Java文件中去,只能通过在包对应的目录中添加一个package.html的文件来达到这个目的。当生成HTML文件时,package.html文件的和部分的内容将会被提取出来当做包的说明。关于包注释,后面还会有更进一步的解释。
(5)概要注释。除了包注释外,还有一种类型的文档无法从Java源文件中提取,就是对所有类文件提供概要说明的文件。同样的,也可以为这类注释单独新建一个HTML文件,这个文件的名字为“overview.html”,它的和标记之间的内容都会被提取。

javadoc 标签

代码中特殊注释——TODO、FIXME、XXX、HACK

TODO:英语翻译为待办事项,备忘录。如果代码中有该标识,说明在标识处有功能代码待编写,待实现的功能在说明中会简略说明。

FIXME:可以拆成短语,fix me ,意为修理我。如果代码中有该标识,说明标识处代码需要修正,甚至代码是错误的,不能工作,需要修复,如何修正会在说明中简略说明。

XXX:如果代码中有该标识,说明标识处代码虽然实现了功能,但是实现的方法有待商榷,希望将来能改进,要改进的地方会在说明中简略说明。

HACK:英语翻译为砍。如果代码中有该标识,说明标识处代码我们需要根据自己的需求去调整程序代码。

Eclipse中特殊的注释:
在Eclipse中,TODO、FIXME和XXX都会被Eclipse的task视图所收集。
在开发过程中在合适的位置添加合适的注释是非常有必要的,我们可以在任务完成前检查这些标记。
Window—>Show View—>Tasks

用法:javadoc [options] [packagenames] [sourcefiles] [@files] -overview <file> 读取 HTML 格式的概述文档 -public 仅显示 public 类和成员 -protected 显示 protected/public 类和成员(缺省) -package 显示 package/protected/public 类和成员 -private 显示所有类和成员 -help 显示命令行选项 -doclet <class> 通过候选 doclet 生成输出 -docletpath <path> 指定 doclet 类文件的查找位置 -1.1 利用 JDK 1.1 模仿 doclet 生成输出 -sourcepath <pathlist> 指定源文件的查找位置 -classpath <pathlist> 指定用户类文件的查找位置 -bootclasspath <pathlist> 覆盖自举类加载器所加载的 类文件的位置 -extdirs <dirlist> 覆盖已安装的扩展的位置 -verbose 有关 Javadoc 所做工作的输出信息 -locale <name> 所用的 Locale,例如 en_US 或 en_US_WIN -encoding <name> 源文件编码名称 -J<flag> 将 <flag> 直接传给运行时系统 由标准 doclet 提供: -d <directory> 输出文件的目标目录 -use 创建类和包的用法页 -version 包含 @version 段 -author 包含 @author 段 -splitindex 将索引分为每个字母对应一个文件 -windowtitle <text> 文档的浏览器窗口标题 -doctitle <html-code> 包含包索引页(首页)的标题 -header <html-code> 包含每一页的页眉文本 -footer <html-code> 包含每一页的页脚文本 -bottom <html-code> 包含每一页的页底文本 -link <url> 创建到 javadoc 输出的链接(位于 <url>) -linkoffline <url> <url2> 利用位于 <url2> 的包列表链接到位于 <url> 的文档 -group <name> <p1>:<p2>.. 将概览页中指定的包分组 -nodeprecated 不包含 @deprecated 信息 -nodeprecatedlist 不生成不鼓励使用的列表 -notree 不生成类层次 -noindex 不生成索引 -nohelp 不生成帮助链接 -nonavbar 不生成导航栏 -helpfile <file> 包含帮助链接功能链接到目标的文件 -stylesheetfile <path> 改变所生成文档的样式的文件 -docencoding <name> 输出编码名称
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值