1.简介
Javadoc用于描述类或者方法的作用。Javadoc可以写在类上面和方法上面。
只有@关键字的内容才会被生成到文档中。
2.写在类上面的Javadoc
写在类上的文档标注一般分为三段:
- 第一段:概要描述,通常用一句或者一段话简要描述该类的作用
- 第二段:详细描述,通常用一段或者多段话来详细描述该类的作用
- 第三段:文档标注,用于标注作者、创建时间、参阅类等信息
例如:
package java.lang;
/**
* Class {@code Object} is the root of the class hierarchy.
* Every class has {@code Object} as a superclass. All objects,
* including arrays, implement the methods of this class.
*/
public class Object {}
2.写在方法上的Javadoc
写在方法上的文档标注一般分为三段:
- 第一段:概要描述,通常用一句或者一段话简要描述该方法的作用,以英文句号作为结束
- 第二段:详细描述,通常用一段或者多段话来详细描述该方法的作用,一般每段话都以英文句号作为结束
- 第三段:文档标注,用于标注参数、返回值、异常、参阅等
方法详细描述上经常使用html标签来,通常都以p标签开始,而且p标签通常都是单标签,不使用结束标签,其中使用最多的就是p标签和pre标签,ul标签, i标签。
pre元素可定义预格式化的文本。被包围在pre元素中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体,pre标签的一个常见应用就是用来表示计算机的源代码。
一般p经常结合pre使用,或者pre结合@code共同使用(推荐@code方式)
一般经常使用pre来举例如何使用方法
例如:
/**
* Check whether the given {@code CharSequence} contains actual <em>text</em>.
* <p>More specifically, this method returns {@code true} if the
* {@code CharSequence} is not {@code null}, its length is greater than
* 0, and it contains at least one non-whitespace character.
* <p><pre class="code">
* StringUtils.hasText(null) = false
* StringUtils.hasText("") = false
* StringUtils.hasText(" ") = false
* StringUtils.hasText("12345") = true
* StringUtils.hasText(" 12345 ") = true
* </pre>
* @param str the {@code CharSequence} to check (may be {@code null})
* @return {@code true} if the {@code CharSequence} is not {@code null},
* its length is greater than 0, and it does not contain whitespace only
* @see Character#isWhitespace
*/
public static boolean hasText(@Nullable CharSequence str) {
return (str != null && str.length() > 0 && containsText(str));
}
4.注释中关键字介绍
标签 |
描述 |
示例 |
@author |
标识一个类的作者 |
@author description |
@deprecated |
指名一个过期的类或成员 |
@deprecated description |
{@docRoot} |
指明当前文档根目录的路径 |
Directory Path |
@exception |
标志一个类抛出的异常 |
@exception exception-name explanation |
{@inheritDoc} |
从直接父类继承的注释 |
Inherits a comment from the immediate surperclass. |
{@link} |
插入一个到另一个主题的链接 |
{@link name text} Miscellaneous {@link String} utility methods. |
{@linkplain} |
插入一个到另一个主题的链接,但是该链接显示纯文本字体 |
Inserts an in-line link to another topic. |
@param |
说明一个方法的参数 |
@param parameter-name explanation @param <E> the type of elements in this list |
@return |
说明返回值类型 |
@return explanation |
@see |
指定一个到另一个主题的链接 |
@see <a href="package-summary.html">java.util.stream</a> @see java.net.URLDecoder#decode(String, String) |
@serial |
说明一个序列化属性 |
@serial description |
@serialData |
说明通过writeObject( ) 和 writeExternal( )方法写的数据 |
@serialData description |
@serialField |
说明一个ObjectStreamField组件 |
@serialField name type description |
@since |
标记当引入一个特定的变化时 |
@since release |
@throws |
和 @exception标签一样. |
The @throws tag has the same meaning as the @exception tag. |
{@value} |
显示常量的值,该常量必须是static属性。 |
Displays the value of a constant, which must be a static field. |
@version |
指定类的版本 |
@version info |
5.代码注释模板设置
在Android Studio 中,File->Settings->Editor->File and Code Templates->Includes->File Header中编辑一下信息
/**
*
*
* @author xxx
* date 2020/9/22 14:25
*/