文档注释
2022-06-30
文档注释
本来以为单行和多行注释没啥好学的，本文只想了解下【文档注释】。写到最后发现，如何优雅的注释本身，也是门大学问。
定义
Java普通注释格式
//
或
/*
*/
Java文档注释格式
/**
@xxx
*/
文档注释主要用于生成javadoc文件的，便于我们对所写的类、方法等进行解释。支持HTML格式。
文档注释目标
https://blog.csdn.net/weixin_39190897/article/details/81880411#/
（1）类注释。类注释用于说明整个类的功能、特性等，它应该放在所有的“import”语句之后，在class定义之前。这个规则也适用于接口（interface）注释。
（2）方法注释。方法注释用来说明方法的定义，比如，方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。
（3）属性注释。默认情况下，javadoc只对公有（public）属性和受保护属性（protected）产生文档——通常是静态常量。
（4）包注释。类、方法、属性的注释都直接放到Java的源文件中，而对于包的注释，无法放到Java文件中去，只能通过在包对应的目录中添加一个package.html的文件来达到这个目的。当生成HTML文件时，package.html文件的和部分的内容将会被提取出来当做包的说明。关于包注释，后面还会有更进一步的解释。
（5）概要注释。除了包注释外，还有一种类型的文档无法从Java源文件中提取，就是对所有类文件提供概要说明的文件。同样的，也可以为这类注释单独新建一个HTML文件，这个文件的名字为“overview.html”，它的和标记之间的内容都会被提取。
文档注释格式
- 概要描述：一段话简要描述基本内容
- 详细描述：几大段描述 功能 和 相关情况
- 文档标注：参数、作者、返回值等
注释标签释义
可参考 https://www.runoob.com/java/java-documentation.html#/ 等
常见的例如：
@author 作者
@param 输入参数
@return 返回参数
@exception 异常
@throws 同exception
@deprecated 指明一个过期的类或成员（不推荐使用的方法）
@version 版本
javadoc 工具
参考 https://www.cnblogs.com/codepeace/archive/2021/04/30/14722083.html#/
-
命令行
在要生成javadoc的.java的文件夹中，cmd输入命令
javadoc -encoding UTF-8 -charset UTF-8 *.java其中
-encoding和-charset分别是编码格式和字符集格式。javadoc命令参数解释，可参考见 https://www.csdn.net/tags/MtjaMgwsMTU4MzAtYmxvZwO0O0OO0O0O.html#/ -
IDE中生成
生成的 index.html 文件，就是我们想要的
多说两句
一般IDE都有提供可以自定义文档注释模板的地方，可以定义适合自己的格式，一劳永逸
有需要的话，可以自己定义文档注释标签
注释侧重WHY，而不是HOW
注释要优雅 https://zhuanlan.zhihu.com/p/41127713#/ ，例如下面的文档注释：
/**
* <p>Checks if CharSequence contains a search character, handling {@code null}.
* This method uses {@link String#indexOf(int)} if possible.</p>
*
* <p>A {@code null} or empty ("") CharSequence will return {@code false}.</p>
*
* <pre>
* StringUtils.contains(null, *) = false
* StringUtils.contains("", *) = false
* StringUtils.contains("abc", 'a') = true
* StringUtils.contains("abc", 'z') = false
* </pre>
*
* @param seq the CharSequence to check, may be null
* @param searchChar the character to find
* @return true if the CharSequence contains the search character,
* false if not or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from contains(String, int) to contains(CharSequence, int)
*/
public static boolean contains(final CharSequence seq, final int searchChar) {
if (isEmpty(seq)) {
return false;
}
return CharSequenceUtils.indexOf(seq, searchChar, 0) >= 0;
}
关于注释的其他
1 巧用标记
- TODO 有未完成的事项
- FIXME 代码有已知问题待修复
- HACK 表示代码有hack逻辑
参考链接
https://www.cnblogs.com/codepeace/archive/2021/04/30/14722083.html#/