【Java】浅谈JavaDoc文档注释
2024-06-05 06:26:04
JavaDoc文档注释
- 文档注释
- JavaDoc标记
- 文档注释示例
- 基于Eclipse IDE的JavaDoc实战
- 后记
文档注释
我们知道，Java有三种注释：
- 单行注释：//
- 多行注释：/* */
- 文档注释：/** */
这里，文档注释是我们探讨的主角。
文档注释可以在程序中嵌入关于程序的信息。我们可以利用JDK提供的javadoc实用程序提取这些信息，并放到HTML文件中。
文档注释使得程序的文档化变得简单，是Java的重要内容。
感兴趣的看一下Java11的API文档吧。
比如java.util.Scanner的网页版官档内容如下：
而我们借助Eclipse IDE查看一下JDK源码：
上面的两个图是Scanner类的部分文档注释截图，可见文档注释里不仅仅有大量的英文注释用于解释，更是有许多@（javadoc标记），还有<></>（HTML文档），内容十分丰富。
当然，其他类也是类似的，因为整个Java API库就是通过这种方式文档化的。
另说：JDK9+开始JavaDoc开始支持模块（Java模块的概念从JDK9正式引入Java体系）
JavaDoc标记
| 标签 | 含义 |
|---|---|
| @author | 标识作者 |
| {@code} | 以代码字体原样显示信息，但不转换成HTML样式 |
| @deprecated | 指定程序元素已经过时 |
| {@docRoot} | 指定当前文档的根目录路径 |
| @exception | 标识某个方法或者构造函数抛出的异常 |
| @hidden | 禁止某元素显示在文档中 |
| {@index} | 给索引指定术语 |
| {@inheritDoc} | 直接从父类中继承文档注释 |
| {@link} | 插入指向另一个主题的内部链接 |
| {@linkplain} | 插入指向另一个主题的内部链接，但以纯文本字体显示链接 |
| {@literal} | 原样式显示信息，但不转换成HTML样式 |
| @param | 文档化形参 |
| @provides | 文档化模块提供的服务 |
| @return | 文档化方法的返回值 |
| @see | 指定对另一个主题的链接 |
| @serial | 文档化默认的可序列化域 |
| @serialData | 文档化writeObject()或writeExternal()方法写入的数据 |
| @serialField | 文档化ObjectStreamField组件 |
| @since | 声明引入特定更改的版本号 |
| {@summary} | 文档化某项的摘要(JDK10+) |
| @throws | 相当于@exception |
| @uses | 文档化模块所需要的服务(JDK9+) |
| {@value} | 显示一个常量的值，该常量必须是静态域 |
| @version | 指定程序元素的版本 |
文档注释示例
/*** This class test class Demo* @author BlankSpace* @version 4.1*/
public class Test {//balabala
}
然后，看一下Scanner类类名上面的完整文档注释（Java每个类都是一大坨这个）
/*** A simple text scanner which can parse primitive types and strings using* regular expressions.** <p>A {@code Scanner} breaks its input into tokens using a* delimiter pattern, which by default matches whitespace. The resulting* tokens may then be converted into values of different types using the* various {@code next} methods.** <p>For example, this code allows a user to read a number from* {@code System.in}:* <blockquote><pre>{@code* Scanner sc = new Scanner(System.in);* int i = sc.nextInt();* }</pre></blockquote>** <p>As another example, this code allows {@code long} types to be* assigned from entries in a file {@code myNumbers}:* <blockquote><pre>{@code* Scanner sc = new Scanner(new File("myNumbers"));* while (sc.hasNextLong()) {* long aLong = sc.nextLong();* }* }</pre></blockquote>** <p>The scanner can also use delimiters other than whitespace. This* example reads several items in from a string:* <blockquote><pre>{@code* String input = "1 fish 2 fish red fish blue fish";* Scanner s = new Scanner(input).useDelimiter("\\s*fish\\s*");* System.out.println(s.nextInt());* System.out.println(s.nextInt());* System.out.println(s.next());* System.out.println(s.next());* s.close();* }</pre></blockquote>* <p>* prints the following output:* <blockquote><pre>{@code* 1* 2* red* blue* }</pre></blockquote>** <p>The same output can be generated with this code, which uses a regular* expression to parse all four tokens at once:* <blockquote><pre>{@code* String input = "1 fish 2 fish red fish blue fish";* Scanner s = new Scanner(input);* s.findInLine("(\\d+) fish (\\d+) fish (\\w+) fish (\\w+)");* MatchResult result = s.match();* for (int i=1; i<=result.groupCount(); i++)* System.out.println(result.group(i));* s.close();* }</pre></blockquote>** <p>The <a id="default-delimiter">default whitespace delimiter</a> used* by a scanner is as recognized by {@link Character#isWhitespace(char)* Character.isWhitespace()}. The {@link #reset reset()}* method will reset the value of the scanner's delimiter to the default* whitespace delimiter regardless of whether it was previously changed.** <p>A scanning operation may block waiting for input.** <p>The {@link #next} and {@link #hasNext} methods and their* companion methods (such as {@link #nextInt} and* {@link #hasNextInt}) first skip any input that matches the delimiter* pattern, and then attempt to return the next token. Both {@code hasNext()}* and {@code next()} methods may block waiting for further input. Whether a* {@code hasNext()} method blocks has no connection to whether or not its* associated {@code next()} method will block. The {@link #tokens} method* may also block waiting for input.** <p>The {@link #findInLine findInLine()},* {@link #findWithinHorizon findWithinHorizon()},* {@link #skip skip()}, and {@link #findAll findAll()}* methods operate independently of the delimiter pattern. These methods will* attempt to match the specified pattern with no regard to delimiters in the* input and thus can be used in special circumstances where delimiters are* not relevant. These methods may block waiting for more input.** <p>When a scanner throws an {@link InputMismatchException}, the scanner* will not pass the token that caused the exception, so that it may be* retrieved or skipped via some other method.** <p>Depending upon the type of delimiting pattern, empty tokens may be* returned. For example, the pattern {@code "\\s+"} will return no empty* tokens since it matches multiple instances of the delimiter. The delimiting* pattern {@code "\\s"} could return empty tokens since it only passes one* space at a time.** <p> A scanner can read text from any object which implements the {@link* java.lang.Readable} interface. If an invocation of the underlying* readable's {@link java.lang.Readable#read read()} method throws an {@link* java.io.IOException} then the scanner assumes that the end of the input* has been reached. The most recent {@code IOException} thrown by the* underlying readable can be retrieved via the {@link #ioException} method.** <p>When a {@code Scanner} is closed, it will close its input source* if the source implements the {@link java.io.Closeable} interface.** <p>A {@code Scanner} is not safe for multithreaded use without* external synchronization.** <p>Unless otherwise mentioned, passing a {@code null} parameter into* any method of a {@code Scanner} will cause a* {@code NullPointerException} to be thrown.** <p>A scanner will default to interpreting numbers as decimal unless a* different radix has been set by using the {@link #useRadix} method. The* {@link #reset} method will reset the value of the scanner's radix to* {@code 10} regardless of whether it was previously changed.** <h3> <a id="localized-numbers">Localized numbers</a> </h3>** <p> An instance of this class is capable of scanning numbers in the standard* formats as well as in the formats of the scanner's locale. A scanner's* <a id="initial-locale">initial locale </a>is the value returned by the {@link* java.util.Locale#getDefault(Locale.Category)* Locale.getDefault(Locale.Category.FORMAT)} method; it may be changed via the {@link* #useLocale useLocale()} method. The {@link #reset} method will reset the value of the* scanner's locale to the initial locale regardless of whether it was* previously changed.** <p>The localized formats are defined in terms of the following parameters,* which for a particular locale are taken from that locale's {@link* java.text.DecimalFormat DecimalFormat} object, {@code df}, and its and* {@link java.text.DecimalFormatSymbols DecimalFormatSymbols} object,* {@code dfs}.** <blockquote><dl>* <dt><i>LocalGroupSeparator </i>* <dd>The character used to separate thousands groups,* <i>i.e.,</i> {@code dfs.}{@link* java.text.DecimalFormatSymbols#getGroupingSeparator* getGroupingSeparator()}* <dt><i>LocalDecimalSeparator </i>* <dd>The character used for the decimal point,* <i>i.e.,</i> {@code dfs.}{@link* java.text.DecimalFormatSymbols#getDecimalSeparator* getDecimalSeparator()}* <dt><i>LocalPositivePrefix </i>* <dd>The string that appears before a positive number (may* be empty), <i>i.e.,</i> {@code df.}{@link* java.text.DecimalFormat#getPositivePrefix* getPositivePrefix()}* <dt><i>LocalPositiveSuffix </i>* <dd>The string that appears after a positive number (may be* empty), <i>i.e.,</i> {@code df.}{@link* java.text.DecimalFormat#getPositiveSuffix* getPositiveSuffix()}* <dt><i>LocalNegativePrefix </i>* <dd>The string that appears before a negative number (may* be empty), <i>i.e.,</i> {@code df.}{@link* java.text.DecimalFormat#getNegativePrefix* getNegativePrefix()}* <dt><i>LocalNegativeSuffix </i>* <dd>The string that appears after a negative number (may be* empty), <i>i.e.,</i> {@code df.}{@link* java.text.DecimalFormat#getNegativeSuffix* getNegativeSuffix()}* <dt><i>LocalNaN </i>* <dd>The string that represents not-a-number for* floating-point values,* <i>i.e.,</i> {@code dfs.}{@link* java.text.DecimalFormatSymbols#getNaN* getNaN()}* <dt><i>LocalInfinity </i>* <dd>The string that represents infinity for floating-point* values, <i>i.e.,</i> {@code dfs.}{@link* java.text.DecimalFormatSymbols#getInfinity* getInfinity()}* </dl></blockquote>** <h4> <a id="number-syntax">Number syntax</a> </h4>** <p> The strings that can be parsed as numbers by an instance of this class* are specified in terms of the following regular-expression grammar, where* Rmax is the highest digit in the radix being used (for example, Rmax is 9 in base 10).** <dl>* <dt><i>NonAsciiDigit</i>:* <dd>A non-ASCII character c for which* {@link java.lang.Character#isDigit Character.isDigit}{@code (c)}* returns true** <dt><i>Non0Digit</i>:* <dd>{@code [1-}<i>Rmax</i>{@code ] | }<i>NonASCIIDigit</i>** <dt><i>Digit</i>:* <dd>{@code [0-}<i>Rmax</i>{@code ] | }<i>NonASCIIDigit</i>** <dt><i>GroupedNumeral</i>:* <dd><code>( </code><i>Non0Digit</i>* <i>Digit</i>{@code ?* }<i>Digit</i>{@code ?}* <dd> <code>( </code><i>LocalGroupSeparator</i>* <i>Digit</i>* <i>Digit</i>* <i>Digit</i>{@code )+ )}** <dt><i>Numeral</i>:* <dd>{@code ( ( }<i>Digit</i>{@code + )* | }<i>GroupedNumeral</i>{@code )}** <dt><a id="Integer-regex"><i>Integer</i>:</a>* <dd>{@code ( [-+]? ( }<i>Numeral</i>{@code* ) )}* <dd>{@code | }<i>LocalPositivePrefix</i> <i>Numeral</i>* <i>LocalPositiveSuffix</i>* <dd>{@code | }<i>LocalNegativePrefix</i> <i>Numeral</i>* <i>LocalNegativeSuffix</i>** <dt><i>DecimalNumeral</i>:* <dd><i>Numeral</i>* <dd>{@code | }<i>Numeral</i>* <i>LocalDecimalSeparator</i>* <i>Digit</i>{@code *}* <dd>{@code | }<i>LocalDecimalSeparator</i>* <i>Digit</i>{@code +}** <dt><i>Exponent</i>:* <dd>{@code ( [eE] [+-]? }<i>Digit</i>{@code + )}** <dt><a id="Decimal-regex"><i>Decimal</i>:</a>* <dd>{@code ( [-+]? }<i>DecimalNumeral</i>* <i>Exponent</i>{@code ? )}* <dd>{@code | }<i>LocalPositivePrefix</i>* <i>DecimalNumeral</i>* <i>LocalPositiveSuffix</i>* <i>Exponent</i>{@code ?}* <dd>{@code | }<i>LocalNegativePrefix</i>* <i>DecimalNumeral</i>* <i>LocalNegativeSuffix</i>* <i>Exponent</i>{@code ?}** <dt><i>HexFloat</i>:* <dd>{@code [-+]? 0[xX][0-9a-fA-F]*\.[0-9a-fA-F]+* ([pP][-+]?[0-9]+)?}** <dt><i>NonNumber</i>:* <dd>{@code NaN* | }<i>LocalNan</i>{@code* | Infinity* | }<i>LocalInfinity</i>** <dt><i>SignedNonNumber</i>:* <dd>{@code ( [-+]? }<i>NonNumber</i>{@code )}* <dd>{@code | }<i>LocalPositivePrefix</i>* <i>NonNumber</i>* <i>LocalPositiveSuffix</i>* <dd>{@code | }<i>LocalNegativePrefix</i>* <i>NonNumber</i>* <i>LocalNegativeSuffix</i>** <dt><a id="Float-regex"><i>Float</i></a>:* <dd><i>Decimal</i>* {@code | }<i>HexFloat</i>* {@code | }<i>SignedNonNumber</i>** </dl>* <p>Whitespace is not significant in the above regular expressions.** @since 1.5*/
基于Eclipse IDE的JavaDoc实战
我们用自己写的顺序表的Project生成JavaDoc。
右键工程，点击Export：
选Javadoc：
我们目前只需要public的，毕竟这是API文档，一直点击next或者finish：
最后一个next有一个JRE的问题，自己处理一下就行，一般不用动。然后点击Yes To All：
瞬间傻掉……这是啥？
我们看一下，GBK编码？哦，想到我用的是UTF-8编码。那就拷过去，换个work-space呗，我还有一个gbk的work-space，再生成：
原来……直接就乱码了，那就文本复制，最简单了！
我再来：
咋还Warning？
原来是我有的@param、@return没有进行说明，以后注意。不过这次就算了，先看看结果：
下面是SequentialList类的JavaDoc文档的一部分：
简单的完成了任务！BINGO！
后记
Java文档注释非常方便，也很好用，建议编程人员养成良好的编程习惯，认真写注释。
另外，现在的IDE非常便捷，能够在你输入/**和回车的时候直接生成文档注释结构。比如在写完一个方法以后，这么做IDE会直接生成包含@param、@return、@throws等在内的基本文档注释，把变量名等直接给出了，很是方便。
而且IDE里如果有良好的文档注释，鼠标放在类名等上时，IDE会给出基本解释（Eclipse）。
Eclipse的@param在生成以后就那个样子了，除非重新生成，否则即使改变变量名也不会引起警告或者错误（生成文档时除外），而IDEA则会给不匹配的文档注释警告报错（红字提示），很人性化。
Eclipse里的文档注释是白色的，挺丑；IDEA里是绿色、斜体，蛮好看的。
【Java】浅谈JavaDoc文档注释相关推荐
- 浅谈在线文档的那些事儿
大厂技术 坚持周更 精选好文 前言 对前端来说开发一个在线文档需要啥技术呢?想一下,开发一个在线文档我们可能要解决的问题: 最基础的文本编辑功能(哦?好像textarea就可以完成,那如果是富文本 ...
- 浅谈onlyoffice文档协作在工程设计中的应用——共享excel计算书
我们设计过程中大量采用excel计算书,因为很多经典的计算都可以用excel解决,最最基本的就是工程量计算啦.稍微复杂的比如钢管计算,埋地钢管结构计算,顶管计算,水力学计算,波浪爬高计算,堤防高程计算 ...
- java文档注释生产api没有注释_如何使用javadoc命令生成api文档，文档注释
/** * 计算器工具类 * * @62616964757a686964616fe78988e69d8331333365646332author GaoHuanjie * @version V1.0 ...
- 【Java】命令行生成JavaDoc文档
编写简单的文档注释 安利 → JavaDoc文档注释详解 /*** @author BlankSpace* @version 1.0*/ public class JavaDocTest {/*** ...
- java文档注释报错,java文档注释主要使用方法
一.java包含哪些注释 1.//用于单行注释. 2./*...*/用于多行注释,从/*开始,到*/结束,不能嵌套. 3./**...*/则是为支持jdk工具javadoc.exe而特有的注释语句.这 ...
- JAVA文档注释规范
JAVA比较规范的文档注释 ...
- Java文档注释用法+JavaDoc的使用详解
Java文档注释+JavaDoc的使用详解 简介 文档注释负责描述类.接口.方法.构造器.成员属性.可以被JDK提供的工具 javadoc 所解析,自动生成一套以网页文件形式体现该程序说明文档的注释. ...
- java 提取文档注释 命令,java文档注释及javadoc命令
注释的三种类型: 1.单行注释(双斜线)// 2.多行注释(一次性将程序的多行注释掉)/*...*/ 3.文档注释:如果编写Java源代码是添加了合适的文档注释,然年后通过JDK提供的Javadoc工 ...
- Java文档注释（利用javadoc生成HTML文档）
目录: 1. 在代码中使用文档注释 2. 类注释 3. 方法注释 4. 域注释 5. 通用注释 6. 包与概述注释 7. 注释的抽取 1. 在代码中使用文档注释 Java 程序员在开发的过程中,或多或 ...
最新文章
- View的Touch事件分发(一.初步了解)
- CSS笔记（十）position属性与定位
- mysql 取某个范围内随机日期
- 文件服务器定时开关机,如何配置作服务器定时开关机.ppt
- 计算机在材料科学的应用论文,计算机在材料科学中的应用论文
- MaxCompute2.0 助力众安保险快速成长
- git关闭密码自动存储_项目在 git 里怎样合理的保存配置文件（服务器密码等敏感内容）...
- Java基础学习总结（19）——Java环境变量配置
- java实现栈的数据结构
- 最全常用正则表达式大全
- android使用libyuv
- 在横道图中如何实现多级项目计划管控
- XV6操作系统make报错Makefile:192: *** recipe commences before first target. Stop. 的解决方法
- oracle 查找不重复的数据,oracle不用distinct查找不重复记录和删除重复记录
- 2018年Oracle官网下载Oracle 11g安装包
- linux mmc 读写,linux内核mmc读写分析
- 带着老娘和女儿看《孔子》
- Odoo 16 企业版手册 - CRM (1）
- 安装PyCharm（最完整版）
- 笔试练习题001...to be continued...