java 注释和嵌入式文档
来源:互联网 发布:戴维南定理实验数据 编辑:程序博客网 时间:2024/06/16 00:58
Java 里有两种类型的注释。
1.第一种是传统的、C 语言风格的注释,是从 C++继承而来的。这些注释用一个“/”起头,随后是注释内容,并可跨越多行,最后用一个“/”结束。注意许多程序员在连续注释内容的每一行都用一个“*”开头,所以经常能看到象下面这样的内容:
/* 这是 * 一段注释,
- 它跨越了多个行 */
但请记住,进行编译时,/和/之间的所有东西都会被忽略,所以上述注释与下面这段注释并没有什么不同:
/* 这是一段注释,它跨越了多个行 */
2.第二种类型的注释也起源于 C++。这种注释叫作“单行注释”,以一个“//”起头,表示这一行的所有内容都是注释。这种类型的注释更常用,因为它书写时更方便。没有必要在键盘上寻找“/”,再寻找“*”(只需按同样的键两次),而且不必在注释结尾时加一个结束标记。下面便是这类注释的一个例子:
// 这是一条单行注释
2.8.1 文档注释
对于 Java 语言,最体贴的一项设计就是它并没有打算让人们为了写程序而写程序——人们也需要考虑程序的文档化问题。对于程序的文档化,最大的问题莫过于对文档的维护。若文档与代码分离,那么每次改变代码后都要改变文档,这无疑会变成相当麻烦的一件事情。解决的方法看起来似乎很简单:将代码同文档“链接”起来。为达到这个目的,最简单的方法是将所有内容都置于同一个文件。然而,为使一切都整齐划一,还必须使用一种特殊的注释语法,以便标记出特殊的文档;另外还需要一个工具,用于提取这些注释,并按有价值的形式将其展现出来。这些都是 Java 必须做到的。
用于提取注释的工具叫作 javadoc。它采用了部分来自 Java 编译器的技术,查找我们置入程序的特殊注释标记。它不仅提取由这些标记指示的信息,也将毗邻注释的类名或方法名提取出来。这样一来,我们就可用最轻的工作量,生成十分专业的程序文档。 javadoc 输出的是一个 HTML 文件,可用自己的 Web 浏览器查看。该工具允许我们创建和管理单个源文件,并
生动生成有用的文档。由于有了 jvadoc,所以我们能够用标准的方法创建文档。而且由于它非常方便,所以我们能轻松获得所有 Java 库的文档。
2.8.2 具体语法
所有 javadoc 命令都只能出现于“/*”注释中。但和平常一样,注释结束于一个“/”。主要通过两种方式来使用 javadoc:嵌入的 HTML,或使用“文档标记”。其中,“文档标记”(Doc tags)是一些以“@”开头的命令,置于注释行的起始处(但前导的“*”会被忽略)。
有三种类型的注释文档,它们对应于位于注释后面的元素:类、变量或者方法。也就是说,一个类注释正好位于一个类定义之前;变量注释正好位于变量定义之前;而一个方法定义正好位于一个方法定义的前面。如下面这个简单的例子所示:
/* 一个类注释 / public class docTest { /* 一个变量注释 / public int i; /* 一个方法注释 /
public void f() {}
}
注意 javadoc 只能为 public(公共)和 protected(受保护)成员处理注释文档。“private”(私有)和“友好”(详见 5 章)成员的注释会被忽略,我们看不到任何输出(也可以用-private 标记包括 private 成员)。这样做是有道理的,因为只有 public 和 protected 成员才可在文件之外使用,这是客户程序员的希望。然而,所有类注释都会包含到输出结果里。
上述代码的输出是一个 HTML 文件,它与其他 Java 文档具有相同的标准格式。因此,用户会非常熟悉这种格式,可在您设计的类中方便地“漫游”。设计程序时,请务必考虑输入上述代码,用 javadoc 处理一下,观看最终 HTML 文件的效果如何。
2.8.3 嵌入 H T M L
javadoc 将 HTML 命令传递给最终生成的 HTML 文档。这便使我们能够充分利用 HTML 的巨大威力。当然,我们的最终动机是格式化代码,不是为了哗众取宠。下面列出一个例子:
/**
System.out.println(new Date()); *
*/
亦可象在其他 Web 文档里那样运用 HTML,对普通文本进行格式化,使其更具条理、更加美观:
/**
所有类型的注释文档一类、域和方法都支持嵌入式html.
2.8.4 一些特殊的标记
介绍一些用于javadoc文档标签。
1.@see:文档引用其他类
所有三种类型的注释文档都可包含@see 标记,它允许我们引用其他类里的文档。对于这个标记,javadoc 会生成相应的 HTML,将其直接链接到其他文档。格式如下:
@see 类名 @see 完整类名
@see 完整类名#方法名
每一格式都会在生成的文档里自动加入一个超链接的“See Also”(参见)条目。注意 javadoc 不会检查我们指定的超链接,不会验证它们是否有效。
- JAVA 注释和嵌入式文档
- JAVA 注释和嵌入式文档
- Java 注释和嵌入式文档
- java 注释和嵌入式文档
- Java注释和嵌入式文档----学习笔记
- 《Java 编程思想》003 Java注释和嵌入式文档
- Thinking in Java——注释和嵌入式文档
- javadoc和Java文档注释
- 第二章.一切都是对象之注释和嵌入式文档javaDoc
- Java基础--->02.单行注释、多行注释,文档注释和API文档。
- Java注释及文档注释
- JAVA 文档注释--JAVADOC文档
- JAVA 文档注释
- java文档注释
- java文档注释
- Java文档注释说明
- java注释文档
- Java文档注释方法
- CSS揭秘读书笔记-第二章 背景与边框
- 第一章 对象导论
- 遇到的android studio崩溃信息整理
- 程序员必知的8大排序
- C进阶之 柔性数组的创建,遍历,删除
- java 注释和嵌入式文档
- Boolan STL与泛型编程 第五周笔记
- SEO优化6月新步法!三点让你领悟
- 如何查看Windows系统的端口号状态及常用命令
- 78. Subsets
- nginx断点续传
- 项目进度(十二)
- 【用Python学习Caffe】7. 网络结构的修剪
- Struts2 path 路径问题说明