JavaDOC注释使用方法word精品文档12页.docx

1、JavaDOC注释使用方法word精品文档12页JavaDOC注释使用方法观察内容的选择，我本着先静后动，由近及远的原则，有目的、有计划的先安排与幼儿生活接近的，能理解的观察内容。随机观察也是不可少的，是相当有趣的，如蜻蜓、蚯蚓、毛毛虫等，孩子一边观察，一边提问，兴趣很浓。我提供的观察对象，注意形象逼真，色彩鲜明，大小适中，引导幼儿多角度多层面地进行观察，保证每个幼儿看得到，看得清。看得清才能说得正确。在观察过程中指导。我注意帮助幼儿学习正确的观察方法，即按顺序观察和抓住事物的不同特征重点观察，观察与说话相结合，在观察中积累词汇，理解词汇，如一次我抓住时机，引导幼儿观察雷雨，雷雨前天空急剧变化

2、，乌云密布，我问幼儿乌云是什么样子的，有的孩子说：乌云像大海的波浪。有的孩子说“乌云跑得飞快。”我加以肯定说“这是乌云滚滚。”当幼儿看到闪电时，我告诉他“这叫电光闪闪。”接着幼儿听到雷声惊叫起来，我抓住时机说：“这就是雷声隆隆。”一会儿下起了大雨，我问：“雨下得怎样?”幼儿说大极了，我就舀一盆水往下一倒，作比较观察，让幼儿掌握“倾盆大雨”这个词。雨后，我又带幼儿观察晴朗的天空，朗诵自编的一首儿歌：“蓝天高，白云飘，鸟儿飞，树儿摇，太阳公公咪咪笑。”这样抓住特征见景生情，幼儿不仅印象深刻，对雷雨前后气象变化的词语学得快，记得牢，而且会应用。我还在观察的基础上，引导幼儿联想，让他们与以往学的词语、

3、生活经验联系起来，在发展想象力中发展语言。如啄木鸟的嘴是长长的，尖尖的，硬硬的，像医生用的手术刀样，给大树开刀治病。通过联想，幼儿能够生动形象地描述观察对象。 目录 要练说，先练胆。说话胆小是幼儿语言发展的障碍。不少幼儿当众说话时显得胆怯：有的结巴重复，面红耳赤；有的声音极低，自讲自听；有的低头不语，扯衣服，扭身子。总之，说话时外部表现不自然。我抓住练胆这个关键，面向全体，偏向差生。一是和幼儿建立和谐的语言交流关系。每当和幼儿讲话时，我总是笑脸相迎，声音亲切，动作亲昵，消除幼儿畏惧心理，让他能主动的、无拘无束地和我交谈。二是注重培养幼儿敢于当众说话的习惯。或在课堂教学中，改变过去老师讲学生听的

4、传统的教学模式，取消了先举手后发言的约束，多采取自由讨论和谈话的形式，给每个幼儿较多的当众说话的机会，培养幼儿爱说话敢说话的兴趣，对一些说话有困难的幼儿，我总是认真地耐心地听，热情地帮助和鼓励他把话说完、说好，增强其说话的勇气和把话说好的信心。三是要提明确的说话要求，在说话训练中不断提高，我要求每个幼儿在说话时要仪态大方，口齿清楚，声音响亮，学会用眼神。对说得好的幼儿，即使是某一方面，我都抓住教育，提出表扬，并要其他幼儿模仿。长期坚持，不断训练，幼儿说话胆量也在不断提高。 前言一. Java 文档和 javadoc二. 文档注释的格式1. 文档注释的格式化2. 文档注释的三部分 三. 使用 j

5、avadoc 标记1. see 的使用2. 使用 author、version 说明类3. 使用 param、return 和 exception 说明方法四. javadoc 命令课本、报刊杂志中的成语、名言警句等俯首皆是,但学生写作文运用到文章中的甚少,即使运用也很难做到恰如其分。为什么?还是没有彻底“记死”的缘故。要解决这个问题,方法很简单,每天花3-5分钟左右的时间记一条成语、一则名言警句即可。可以写在后黑板的“积累专栏”上每日一换,可以在每天课前的3分钟让学生轮流讲解,也可让学生个人搜集,每天往笔记本上抄写,教师定期检查等等。这样,一年就可记300多条成语、300多则名言警句,日积月

6、累,终究会成为一笔不小的财富。这些成语典故“贮藏”在学生脑中,自然会出口成章,写作时便会随心所欲地“提取”出来,使文章增色添辉。 前言 Java 的语法与 C+ 及为相似，那么，你知道 Java 的注释有几种吗？是两种？ / 注释一行/* . */ 注释若干行不完全对，除了以上两种之外，还有第三种，文档注释：/* . */ 注释若干行，并写入 javadoc 文档通常这种注释的多行写法如下：一. Java 文档和 javadocJava 程序员都应该知道使用 JDK 开发，最好的帮助信息就来自 SUN 发布的 Java 文档。它分包、分类详细的提供了各方法、属性的帮助信息，具有详细的类树信息、

7、索引信息等，并提供了许多相关类之间的关系，如继承、实现接口、引用等。Java 文档全是由一些 html 文件组织起来的，在 SUM 的站点上可以下载它们的压缩包。但是你肯定想不到，这些文档我们可以自己生成。安装了 JDK 之后，安装目录下有一个 src.jar 文件或者 src.zip 文件，它们都是以 ZIP 格式压缩的，可以使用 WinZip 解压。解压之后，我们就可以看到分目录放的全是 .java 文件。是了，这些就是 Java 运行类的源码了，非常完整，连注释都写得一清二楚不过，怎么看这些注释都有点似曾相识的感觉？这就不奇怪了，我们的迷底也快要揭开了。如果你仔细对比一下 .java 源

8、文件中的文档注释 (/* . */) 和 Java 文档的内容，你会发现它们就是一样的。Java 文档只是还在格式和排版上下了些功夫。再仔细一点，你会发现 .java 源文件中的注释还带有 HTML 标识，如 、 等，在 Java 文档中，该出现这些标识的地方，已经按标识的的定义进行了排版。终于真像大白了，原来 Java 文档是来自这些注释。难怪这些注释叫做文档注释呢！不过，是什么工具把这些注释变成文档的呢？是该请出 javadoc 的时候了。在 JDK 的 bin 目录下你可以找到 javadoc，如果是 Windows 下的 JDK，它的文件名为 javadoc.exe。使用 javdoc

9、 编译 .java 源文件时，它会读出 .java 源文件中的文档注释，并按照一定的规则与 Java 源程序一起进行编译，生成文档。介绍 javadoc 的编译命令之前，还是先了解一下文档注释的格式吧。不过为了能够编译下面提到的若干例子，这里先介绍一条 javadoc 命令：javadoc -d 文档存放目录 -author -version 源文件名.java这条命令编译一个名为 “源文件名.java”的 java 源文件，并将生成的文档存放在“文档存放目录”指定的目录下，生成的文档中 index.html 就是文档的首页。-author 和 -version 两个选项可以省略。二. 文档注

10、释的格式文档注释可以用于对类、属性、方法等进行说明。写文档注释时除了需要使用 /* . */ 限定之外，还需要注意注释内部的一些细节问题。1. 文档和文档注释的格式化生成的文档是 HTML 格式，而这些 HTML 格式的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入 ，如果要分段，就应该在段前写入 。因此，格式化文档，就是在文档注释中添加相应的 HTML 标识。文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输入到文档的。如/* This is f

11、irst line. * This is second line. This is third line.*/编译输出后的 HTML 源码则是This is first line. This is second line. This is third line.前导的 * 号允许连续使用多个，其效果和使用一个 * 号一样，但多个 * 号前不能有其它字符分隔，否则分隔符及后面的 * 号都将作为文档的内容。* 号在这里是作为左边界使用，如上例的第一行和第二行；如果没有前导的 * 号，则边界从第一个有效字符开始，而不包括前面的空格，如上例第三行。还有一点需要说明，文档注释只说明紧接其后的类、属性或者

12、方法。如下例：/* comment for class */public class Test /* comment for a attribute */ int number; /* comment for a method */ public void myMethod() . .上例中的三处注释就是分别对类、属性和方法的文档注释。它们生成的文档分别是说明紧接其后的类、属性、方法的。“紧接”二字尤其重要，如果忽略了这一点，就很可能造成生成的文档错误。如import java.lang.*;/* commnet for class */public class Test . / 此例为正确的

13、例子这个文档注释将生成正确的文档。但只需要改变其中两行的位置，变成下例，就会出错：/* commnet for class */import java.lang.*;public class Test . / 此例为错误的例子这个例子只把上例的 import 语句和文档注释部分交换了位置，结果却大不相同生成的文档中根本就找不到上述注释的内容了。原因何在？“/* commnet for class */”是对 class Test 的说明，把它放在“public class Test . ”之前时，其后紧接着 class Test，符合规则，所以生成的文档正确。但是把它和“import java

14、.lang.*;”调换了位置后，其后紧接的就是不 class Test 了，而是一个 import 语句。由于文档注释只能说明类、属性和方法，import 语句不在此列，所以这个文档注释就被当作错误说明省略掉了。2. 文档注释的三部分根据在文档中显示的效果，文档注释分为三部分。先举例如下，以便说明。/* * show 方法的简述. * show 方法的详细说明第一行 * show 方法的详细说明第二行 * param b true 表示显示，false 表示隐藏 * return 没有返回值 */public void show(boolean b) frame.show(b);第一部分是简述

15、。文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明。列表中属性名或者方法名后面那段说明就是简述。如下图中被红框框选的部分：简述部分写在一段文档注释的最前面，第一个点号 (.) 之前 (包括点号)。换句话说，就是用第一个点号分隔文档注释，之前是简述，之后是第二部分和第三部分。如上例中的 “* show 方法的简述.”。有时，即使正确地以一个点号作为分隔，javadoc 仍然会出错，把点号后面的部分也做为了第一部分。为了解决这个问题，我们可以使用一个 标志将第二分部分开为下一段，如上例的“* show 方法的详细说明第一行 .”。除此之外，我们也可以使用 来分隔。第二部分是

16、详细说明部分。该部分对属性或者方法进行详细的说明，在格式上没有什么特殊的要求，可以包含若干个点号。它在文档中的位置如下图所示：这部分文档在上例中相应的代码是：* show 方法的简述.* show 方法的详细说明第一行* show 方法的详细说明第二行发现什么了？对了，简述也在其中。这一点要记住了，不要画蛇添足在详细说明部分中再写一次简述哦！第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。它在文档中的位置：第三部分在上例中相应的代码是 * param b true 表示显示，false 表示隐藏* return 没有返回值除了 param 和 return 之外，还有其它的

17、一些特殊标记，分别用于对类、属性和方法的说明不要推我，我马上就说。三. 使用 javadoc 标记javadoc 标记是插入文档注释中的特殊标记，它们用于标识代码中的特殊引用。javadoc 标记由“”及其后所跟的标记类型和专用注释引用组成。记住了，三个部分、标记类型、专用注释引用。不过我宁愿把它分成两部分： 和标记类型、专用注释引用。虽然 和 标记类型之间有时可以用空格符分隔，但是我宁愿始终将它们紧挨着写，以减少出错机会。javadoc 标记有如下一些：标记用于作用author对类的说明标明开发该类模块的作者version对类的说明标明该类模块的版本see对类、属性、方法的说明参考转向，也就

18、是相关主题param对方法的说明对方法中某参数的说明return对方法的说明对方法返回值的说明exception对方法的说明对方法可能抛出的异常进行说明下面详细说明各标记。1. see 的使用see 的句法有三种： see 类名see #方法名或属性名see 类名#方法名或属性名类名，可以根据需要只写出类名 (如 String) 或者写出类全名 (如 java.lang.String)。那么什么时候只需要写出类名，什么时候需要写出类全名呢？如果 java 源文件中的 import 语句包含了的类，可以只写出类名，如果没有包含，则需要写出类全名。java.lang 也已经默认被包含了。这和 ja

19、vac 编译 java 源文件时的规定一样，所以可以简单的用 javac 编译来判断，源程序中 javac 能找到的类，javadoc 也一定能找到；javac 找不到的类，javadoc 也找不到，这就需要使用类全名了。方法名或者属性名，如果是属性名，则只需要写出属性名即可；如果是方法名，则需要写出方法名以及参数类型，没有参数的方法，需要写出一对括号。如成员类型成员名称及参数see 句法属性numbersee number属性countsee count方法count()see count()方法show(boolean b)see show(boolean)方法main(String ar

20、gs)see main(String)有时也可以偷懒：假如上例中，没有 count 这一属性，那么参考方法 count() 就可以简写成 see count。不过，为了安全起见，还是写全 see count() 比较好。see 的第二个句法和第三个句法都是转向方法或者属性的参考，它们有什么区别呢？第二个句法中没有指出类名，则默认为当前类。所以它定义的参考，都转向本类中的属性或者方法。而第三个句法中指出了类名，则还可以转向其它类的属性或者方法。关于 see 标记，我们举个例说明。由于 see 在对类说明、对属性说明、对方法说明时用法都一样，所以这里只以对类说明为例。/* * see String

21、 * 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() 虽然在本类中也有 (从 O

22、bject 继承的)，但我们是想参考 Object 类的 toString() 方法，所以使用了 Object#toString()。奇怪的是，为什么其中只有 str、str() 和 main(String) 变成了链接呢？那是因为编译时没有把 java.lang 包或者 Stirng、StringBuffer、Object 三个类的源文件一起加入编译，所以，生成的文档没有关于那三个类的信息，也就不可以建立链接了。后面讲解 javadoc 编译命令的时候还会详细说明。上例中如果去把类中的 str 属性去掉，那么生成的文档又会有什么变化呢？你会发现，原来是 str, str()，而现在变成了 s

23、tr(), str()，因为 str 属性已经没有了，所以 str 也表示方法 str()。2. 使用 author、version 说明类这两个标记分别用于指明类的作者和版本。缺省情况下 javadoc 将其忽略，但命令行开关 -author 和 -version 可以修改这个功能，使其包含的信息被输出。这两个标记的句法如下：author 作者名version 版本号其中，author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。version 也可以使用多次，只有第一次有效，生成的文档中只会显示第一次使用 version 指明的版本号。如下例/* * au

24、thor Fancy * author Bird * version Version 1.00 * version Version 2.00 */public class TestJavaDoc 生成文档的相关部分如图：从生成文档的图示中可以看出，两个 author 语句都被编译，在文档中生成了作者列表。而两个 version 语句中只有第一句被编译了，只生成了一个版本号。从图上看，作者列表是以逗号分隔的，如果我想分行显示怎么办？另外，如果我想显示两个以上的版本号又该怎么办？我们可以将上述两条 author 语句合为一句，把两个 version 语句也合为一句：author FancyBird

25、version Version 1.00Version 2.00结果如图：我们这样做即达到了目的，又没有破坏规则。author 之后的作者名和 version 之后的版本号都可以是用户自己定义的任何 HTML 格式，所以我们可以使用 标记将其分行显示。同时，在一个 version 中指明两个用 分隔的版本号，也没有破坏只显示第一个 version 内容的规则。3. 使用 param、return 和 exception 说明方法这三个标记都是只用于方法的。param 描述方法的参数，return 描述方法的返回值，exception 描述方法可能抛出的异常。它们的句法如下：param 参数名

26、参数说明return 返回值说明exception 异常类名 说明每一个 param 只能描述方法的一个参数，所以，如果方法需要多个参数，就需要多次使用 param 来描述。一个方法中只能用一个 return，如果文档说明中列了多个 return，则 javadoc 编译时会发出警告，且只有第一个 return 在生成的文档中有效。方法可能抛出的异常应当用 exception 描述。由于一个方法可能抛出多个异常，所以可以有多个 exception。每个 exception 后面应有简述的异常类名，说明中应指出抛出异常的原因。需要注意的是，异常类名应该根据源文件的 import 语句确定是写出类

27、名还是类全名。 示例如下：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

28、Exception switch (n.intValue() case 0: break; case 1: throw new Exception(Test Only); default: return false; return true; 使用 javadoc 编译生成的文档相关部分如下图：可以看到，上例中 param b excrescent parameter 一句是多余的，因为参数只是一个 n，并没有一个 b 但是 javadoc 编译时并没有检查。因此，写文档注释时一定要正确匹配参数表与方法中正式参数表的项目。如果方法参数表中的参数是 a，文档中却给出对参数 x 的解释，或者再多出

29、一个参数 i，就会让人摸不着头脑了。exceptin 也是一样。上例程序中并没有抛出一个 NullPointerException，但是文档注释中为什么要写上这么一句呢，难道又是为了演示？这不是为了演示描述多余的异常也能通过编译，而是 为了说明写异常说明时应考运行时 (RunTime) 异常的可能性。上例程序中，如果参数 n 是给的一个空值 (null)，那么程序会在运行的时候抛出一个 NullPointerException，因此，在文档注释中添加了对 NullPointerException 的说明。上例中的 return 语句有两个，但是根据规则，同一个方法中，只有第一个 return 有效，其余的会被 javadoc 忽略。所以生成的文档中没有出现第二个 return 的描述。讲到这里，该怎么写文档注释你应该已经清楚了，下面就开始讲解 javadoc 的常用命令。四. javadoc 命令运行 javadoc -help 可以看到 javadoc 的用法，这里列举常用参数如下：用法：javadoc options packagenames sourcefiles选项：-public仅显示 public 类和成员 -protected显示 protected/