文档注释的结构

  文档注释主体的开头是一句话,概述类型或成员的作用,应自成一体。后面可跟其他句子或段落,用以详细说明类、接口、方法或字段。

  除了这些描述性的段落以外,后也可跟其他段落,数量不限,并且每段以一个特殊的文档注释标签开头,如@author、@param、@returns。这些包含标签的段落提供类、接口、方法或字段的特殊信息,javadoc会以标准形式显示这些信息。

  文档注释的描述性内容可以包含简单的HTML标记标签,在这里列举几个常用的:

  •   <i>name</i> 表示强调
  •   <code>name</code> 用于显示类、方法和字段的名称
  •   <pre>name</pre> 用于显示多行代码示例
  •   <p>name</p> 把说明分成多个段落
  •   <ul><li>name</li><ul> 用于显示无序列表等结构
  •   如果想引入图片,则需要将图片放在源码目录的doc-files子目录中,且要使用类名和一个整数后缀命名这张图片。如<img src="doc-files/Circle-2.jpg">

  需要注意的是,由于javadoc提取的文档是个html,因此,为了避免你的文档注释影响所生成的html文件,你的文档注释是不能包含html主结构标签的,例如<h2></h2>以及<hr></hr>。此外,还应该避免使用<a>link</a>标签引入超链接或交叉引用,如果有这方面的需求,应使用特殊的文档注释标签,后续小节将会提及。

文档注释标签

  @author name

    添加一个“Author:”条目,内容是指定的名字。每个类和接口的定义都应该使用这个标签,但单个方法和字段一定不能使用。如果有多个作者,可如下形式使用多个该标签:

      @author Ben Evans

      @author Ju Mao

    要求:多位作者按顺序列出,按照作者的时间顺序,从最初作者开始列,如果作者未知,可用unascribed。

  @version text

    插入一个“Version:”条目,内容是,指定的文本,如:

    @version 1.32, 18/11/07

    表示类或方法的版本是1.32,在18年11.7号更新。每个类和接口都应该包含这个标签,单个方法和字段不能使用。这个标签经常和支持自动排序版本号的版本控制系统使用。

    如果不指定命令行参数-versio, javadoc不会输出版本信息。

  @param parameter-name description

    把指定的参数及其说明添加到当前方法的“Parameters:”区域。

    在方法和构造方法的文档注释中,每个参数都要使用一个@param标签列出,而且应该按照参数传入的顺序排列。  

    这个标签只能出现在方法和构造方法的文档注释中。

    为便于阅读,通常采用如下格式:

    @param o  要插入对象

    @param index  插入对象位置

  @return description

    插入一个“Returns:”区域,内容是指定的说明。

    每个方法都应该使用这个注释标签,除非方法返回值为void,或者是构造方法。

    说明需要多长就写多长,但为了保持简洁,如下使用句子片段:

    @return <code>true</code>:  成功插入

        <code>false</code>:  列表中已经包含要插入的对象

  @exception full-classname description

    添加一个“Throws:”条目,内容是指定的异常名称和说明。方法和构造方法的文档注释应该为throws子句中的每个已检异常编写一个@exception标签,如:

    @exception java.io.FileNotFoundException

               如果找不到指定文件

    如果方法的用户基于某种原因想捕获当前方法抛出的未检异常,@exception标签也可以为这些未检异常编写文档。

    如果方法能抛出多个异常,要在相邻的几行使用多个@exception标签,而且按照异常名称的字母表顺序排列。

    该标签只能出现在方法和构造方法的文档注释中。

    @throws标签是@exception标签的别名。

  @deprecated explanation

    该标签指明随后的类型或成员弃用了,应该避免使用。

    这个文本应该说明这个类或成员何时开始被弃用,如果可能的话,还应该推荐替代的类或成员,并且添加只想替代类或成员的链接,如:

    @deprecated 从3.0版本开始,这个方法被{@link #setColor}替代了。

    {@link #setColor}标签是java文档注释中,所用的正确的超链接引用格式,后续会说明。

  @since version

    指明类型或成员何时添加到API中。这个标签后面应该跟着版本号或其他形式的版本。例如:

    @since JNUT 3.0

    每个类型的文档注释都应该包含一个@since标签

    类型版本之后添加的任何成员,都要在其文档注释中加上@since标签

  @serial description

    类序列化的方式是公开API的一部分。如果类能序列化,就应该在文档注释中,使用这个标签来说明序列化的格式。

    在实现Serializable接口的类中,组成序列化状态的每个字段,都应该在其文档注释中使用该标签

    对于使用默认序列化机制的类来说,除了声明为transient的字段,其他所有字段,包括声明为private的字段,都要在文档中使用该标签。

    description应该简要说明字段及其在序列化对象中的作用。

    在类和包的文档注释中,也可以使用@serial标签,指明是否为当前类或包生成“Serialized Form”界面。句法如下:

    @serial include

    @serial excude

  @serialField name type description

    实现Serializable接口的类可以声明一个名为serialPersistentFields的字段,定义序列化格式。

    serialPersistentFields字段的值是一个数组,由ObjectStreamField对象组成。

    对这样的类来说,在serialPersistentFields字段的文档注释里,数组中的每个元素都要使用一个@serialField标签列出,每个标签都要指明元素在类序列化状态中的名称、类型和作用。

  @serialData description

    实现Serializable接口的类可以定义一个writeObject()方法,用于写入数据,代替默认序列化机制提供的写入方法。

    实现Externalizable接口的类可以定义一个writeExternal()方法,该方法把对象的完整状态写入序列化流。

    writeObject()和writeExternal()方法的文档注释中应该使用@serialData标签,description应该说明这个方法的序列化格式。

行内文档注释标签

  在文档注释中,只要能使用html文本的地方,都能使用行内标签。因为这些标签直接出现在html文本流中,所以要花括号把标签中的内容和周围的html文本隔开。

  {@link reference}

    {@link}标签和@see标签的作用类似,但@see标签是在专门的“See Also:”区域放一个指向引用的链接,而{@link}标签在行内插入链接。

    在文档注释中,只要能使用html文本的地方,都可以使用{@link}标签。

    {@link}标签可以出现在类、接口、方法或字段的第一句话,也能出现在@param、@returns、@exception、@deprecated标签的说明中。

    {@link}标签中的reference使用专门的句法:

      • 如果reference以引号开头,表示书名或其他出版物的名称,参数值是什么就显示什么
      • 如果reference以<符号开头,表示使用<a>标签标记的任意html超链接,这个超链接会原样插入生成的文档
      • 如果reference既不是引号中的字符串,也不是超链接,那么应该具备如下格式:

            feature [label]

         此时,javadoc会把label当成超链接的文本,指向feature指定的内容。如果没指定label(一般都不指定),javadoc会使用feature作为超链接的文本。

         feature可以指向包、类型或类型的成员,使用下述格式的一种:

        • pkgname:指向指定的包

             @see java.lang.reflect

        • pkgname.typename:指定完整的包名,指向对应的类、接口、枚举类型或注解类型

            @see java.util.List

        • typename:不指定包名,指向对应的类型

            @see List

            javadoc会搜索当前包和typename类导入的所有类,解析这个引用

        • typename#methodname:指向指定类型中指定名称对应的方法或构造方法。

             @see java.io.InputStream#reset

             @see InputStream#close

            如果类型不包含包名,会按照typename使用的方式解析。如果方法重载了,或类中定义有同名字段,这种句法会引起歧义。

        • typename#methodname(paramtypes):指向指定类型中指定名称对应的方法或构造方法,而且明确指定参数的类型。

              交叉引用重载的方法时可以使用这种格式,例如:

              @see InputStream#read(byte[], int,int)

        • #methodname

            指向一个没有重载的方法或构造方法,这个方法在当前类或接口中,或者在当前类或接口的某个外层类、超类或超链接中。

            这个简短格式用于指向同一个类中的其他方法。例如:

            @see #setBackgroundColor

        • #methodname(paramtypes)

            指向当前类、接口或者某个超类、外层类中的方法或构造方法。这种格式可以指向重载的方法,因为它明确列出方法参数的类型。例如:

            @see #setPosition(int,int)

        • typename#fieldname:指向指定类中的指定字段

            @see java.io.BufferedInputStream#buf

            如果类型不包含包名,会按照typename使用的方式解析。

        • #fieldname

            指向一个字段,这个字段在当前类型中,或者在当前类型的某个外层类、超类或超链接中。例如:

              @see #x

  {@linkplain reference}

    {@linkplain}标签和{@link}标签的作用类似,不过,在{@linkplain}标签生成的链接中,链接文字使用的是普通字体,而{@link}标签使用代码字体。

    如果reference包含要链接的feature和指明链接替代文本的label,就要使用{@linkplain}

  {@inheritDoc}

    如果一个方法覆盖了超类的方法,或者实现了接口中的方法,那么这个方法的文档注释可以省略一些内容,让javadoc自动从被覆盖或被实现的方法中继承。

    {@inheritDoc}标签可以继承单个标签的文本,还能在继承的基础上再添加一些说明。继承单个标签的方式如下所示:

      @param index @{inheritDoc}

      @return @{inheritDoc}

  {@docRoot}

    这个行内标签没有参数,javadoc生成文档时会把它替换成文档的根目录。

    这个标签在引用外部文件的超链接中很有用,例如引用图片或者一份版权声明:

    <img src="{@docroot}/images/logo.gif">

    这份资料受<a href="{@docroot}/legal.html">版权保护</a>

  {@literal text}

    这个行内标签按照字面形式显示text,text中的所有html都会转义,而且所有javadoc标签都会被忽略。

    虽然不保留空白格式,但仍适合在<pre>标签中使用。

  {@code text}

    这个标签和{@literal}标签的作用类似,但会使用代码字体显示text的字面量。等价于:

    &lt;code&gt;{@literal <replaceable>text</replaceable>}&lt;/code&gt;

  {@value}

    没有参数的{@value}标签在static final字段的文档注释中使用,会被替换成当前字段的常量值。

  {@value reference}

    这种{@value}标签的变体有一个reference参数,指向一个static final字段,会被替换成指定字段的常量值。

Java Learning之文档注释的更多相关文章

  1. 005、Java中使用文档注释

    01. 代码如下: package TIANPAN; /** * 此处为文档注释 * @author 田攀 微信382477247 */ public class TestDemo { public ...

  2. 新建Java文件的 文档注释

    /** * <br> * ============================================= * * @author : Liuyc * @company : 版权 ...

  3. [JAVA] JAVA 文档注释

    Java 程序设计环境 文档注释 javadoc JDK中包含的javadoc工具可以由源文件生成一个HTML文档. javadoc从以下几个特性中抽取信息 包 公有类与接口 公有的和受保护的构造器及 ...

  4. Java的文档注释之生成帮助文档

    示例: /** * Title: Person类<br/> * Description:通过Person类说明Java中的文档注释<br/> * Company: *** * ...

  5. java文档注释规范(一)

    https://blog.csdn.net/huangsiqian/article/details/82725214 Javadoc工具将从四种不同类型的“源”文件生成输出文档:Java语言类的源文件 ...

  6. API文档注释 Javadoc

    阅读API文档 JDK包结构 JDK包是由sun开发的一组已经实现的类库,.JDK根据提供的功能不同,将类库划分为若干个包,比如用于操作输入输出的  java.io包,java程序语言设计基础类的   ...

  7. java文档注释--javadoc的用法

    1.前言 Java中有三种注释方式.前两种分别是 // 和 /* */,主要用于代码的注释,以此来方便代码的可读性.第三种被称作说明注释或文档注释,它以 /** 开始,以 */结束,文档注释允许你在程 ...

  8. [java基础]文档注释

    转载自:http://blog.163.com/hui_san/blog/static/5710286720104191100389/ 前言 Java 的语法与 C++ 及为相似,那么,你知道 Jav ...

  9. Java 文档注释

    Java只是三种注释方式.前两种分别是// 和/* */,第三种被称作说明注释,它以/** 开始,以 */结束. 说明注释允许你在程序中嵌入关于程序的信息.你可以使用javadoc工具软件来生成信息, ...

随机推荐

  1. node 集群与稳定

    node集群搭建好之后,还需要考虑一些细节问题. 性能问题 多个工作进程的存活状态管理 工作进程的平滑重启 配置或者静态数据的动态重新载入 其它细节 1 进程事件 Node子进程对象除了send()方 ...

  2. vue入门之单文件组件

    介绍 在很多 Vue 项目中,我们使用 Vue.component 来定义全局组件,紧接着用 new Vue({ el: '#container '}) 在每个页面内指定一个容器元素. 这种方式在很多 ...

  3. HDU 1556 Color the ball (一维树状数组,区间更新,单点查询)

    中文题,题意就不说了 一开始接触树状数组时,只知道“单点更新,区间求和”的功能,没想到还有“区间更新,单点查询”的作用. 树状数组有两种用途(以一维树状数组举例): 1.单点更新,区间查询(即求和) ...

  4. 配置idea

    http://www.cnblogs.com/yangyquin/p/5285272.html

  5. LeetCode 404. Sum of Left Leaves (C++)

    题目: Find the sum of all left leaves in a given binary tree. Example: 3 / \ 9 20 / \ 15 7 There are t ...

  6. Scrum立会报告+燃尽图(十二月九日总第四十次):视频剪辑与用户反馈

    此作业要求参见:https://edu.cnblogs.com/campus/nenu/2018fall/homework/2484 项目地址:https://git.coding.net/zhang ...

  7. Daily Scrumming 2015.10.22(Day 3)

    今明两天任务表 Member Today’s Task Tomorrow’s Task 江昊 学习rails ActiveRecord 购买.注册域名 继续学习rails ActiveRecord 数 ...

  8. 接着继续(OO博客第四弹)

    .测试与JSF正确性论证 测试和JSF正确性论证是对一个程序进行检验的两种方式.测试是来的最直接的,输入合法的输入给出正确的提示,输入非法的输入给出错误信息反馈,直接就能很容易的了解程序的运行情况.但 ...

  9. 炸弹人——NABCD分析

    炸弹人——NABCD分析结果 N:需求:本软件应用于学生,学生可以在课余时间放松心情,缓解学习压力. A:做法:使用Cocosdx和Visual Studio 2010结合,之间用Python使其结合 ...

  10. DPDK helloworld 源码阅读

    在 DPDK Programmer's Guides 中的 EAL 一篇中有一个图可以很清晰地看到一个DPDK的应用程序的大致执行思路: 初始化检查CPU支持.微架构配置等完成后,执行main()函数 ...