java 文档注释

JDK 包含 个很有用的工具,叫做javadoc ,它可以由源文件生成 HTML 文档。事 实上,在第 章讲述的联机 API 文档就是通过对标准 Java 类库的源代码运行javadoc 成的 如果在源代码中添加以专用的定界符/**开始的注释,那么可以很容易地生成 个看上 去具有专业水准的文档 这是一种很好的方式,因为这种方式可以将代码与注释保存在一个 地方 如果将文档存入 个独立的文件中,就有可能会随着时间的推移,出现代码和注释不 致的问题 然而,由于文档注释与源代码在同 个文件中,在修改源代码的同时, 重新运 javadoc 就可以轻而易举地保持两者的一致性            注释的插入 javadoc 实用程序(utility )从下面几个特性中抽取信息: .包 ·公有类与接口 ·公有的和受保护的构造器及方法 ·公有的和受保护的域 在第 章中将介绍受保护特性,在第 章将介绍接口 应该为上面几部分编写注释 注释应该放置在所描述特性的前面 注释以/忡开始,并 以*/结束 每个/** ... /文档注释在标记之后紧跟着*格式文本( free-form text )。 标记由 @开 始,如@author 或@param *格式文本的第一句应该是一个概要性的句子 javadoc 实用程序自动地将这些句子抽 取出来形成概要页 在*格式文本中,可以使用 HT~ 修饰符,例如,用于强调的<em>... </em 着重强调的< trong ... </ strong>以及包含图像的<img ... >等 不过,-定不要使用<hl >或 >,因为它们会与文档的格式产生冲 若要键入等宽代码, 使用{@code ... }而不是 code>…</code 一寸主样 来,就不用操心对代码中的<字符转义了   注释:如果文档中有到其他文件的链接,例如,图像文件 用户界面的组件的图表或 像等),就应该将这些文件放到子目录 doc-files javadoc 实用程序将从源目录拷贝这 些目录及其中的文件到文档目录中 在链接中需妥使用 doc-files 目录,例如:<img src “ doc-files/um!. png ” alt=“UMLdiagram ”> 4.9.2 类注释 类注释必须放在 import 语句之后,类定义之前   java     文档注释

 

 

方法注释 每一个方法注释必须放在所描述的方法之前 除了通用标记之外,还可以使用下面的标记: • @param 描述 这个标记将对当前方法的“ param ”(参数)部分添加一个条目 这个描述可以占据多 行,并可以使用 HTML 标记。一个方法的所有@param 标记必须放在 • @return 描述 这个标记将对当前方法添加“ return ”(返回)部分 这个描述可以跨越多行,井可以 使用 HTML 标记 • @throws 描述 这个标记将添加 个注释,用于表示这个方法有可能抛出异常 有关异常的详细内容 将在第 10 中讨论 下面是 个方法注释的示例:     java     文档注释

 

 

域注释 只需要对公有域(通常指的是静态常量)建立文档 例如,       java     文档注释

 

 

java     文档注释

 

 

        java     文档注释

 

 

    java     文档注释

 

 

    java     文档注释

 

 

        java     文档注释

 

 

    java     文档注释

 

 

                                     
上一篇:Java基础语法之注释


下一篇:01.java基础知识