简介
说明
本文介绍Java Doc(文档注释)的用法。
官网
https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
Java Doc注解
标签 | 描述 | 示例 |
@author | 标识一个类的作者 | @author description |
@deprecated | 指名一个过期的类或成员 | @deprecated description |
{@docRoot} | 指明当前文档根目录的路径 | Directory Path |
@exception | 标志一个类抛出的异常 | @exception exception-name explanation |
@version | 指定版本 | @version info |
{@inheritDoc} | 从直接父类继承的注释 | Inherits a comment from the immediate surperclass. |
{@link} | 插入一个到另一个主题的链接 | {@link name text} |
{@linkplain} | 插入一个到另一个主题的链接,但是该链接显示纯文本字体 | Inserts an in-line link to another topic. |
@param | 说明一个方法的参数 | @param parameter-name explanation |
@return | 说明返回值类型 | @return explanation |
@see | 指定一个到另一个主题的链接 | @see anchor |
@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. |
写在类上面的JavaDoc
写在类上的文档标注一般分为三段:
- 第一段:概要描述,通常用一句或者一段话简要描述该类的作用,以英文句号作为结束
- 第二段:详细描述,通常用一段或者多段话来详细描述该类的作用,一般每段话都以英文句号作为结束
- 第三段:文档标注,用于标注作者、创建时间、参阅类等信息
第一段:概要描述
单行示例:
package org.springframework.jdbc.core; /** * Simple adapter for {@link PreparedStatementSetter} that applies a given array of arguments. * */ public class ArgumentPreparedStatementSetter implements PreparedStatementSetter, ParameterDisposer { }
多行示例:
package java.lang; /** * The {@code Long} class wraps a value of the primitive type {@code * long} in an object. An object of type {@code Long} contains a * single field whose type is {@code long}. * * <p> In addition, this class provides several methods for converting * a {@code long} to a {@code String} and a {@code String} to a {@code * long}, as well as other constants and methods useful when dealing * with a {@code long}. * * <p>Implementation note: The implementations of the "bit twiddling" * methods (such as {@link #highestOneBit(long) highestOneBit} and * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are * based on material from Henry S. Warren, Jr.'s <i>Hacker's * Delight</i>, (Addison Wesley, 2002). * * @author Lee Boynton * @author Arthur van Hoff * @author Josh Bloch * @author Joseph D. Darcy * @since JDK1.0 */ public final class Long extends Number implements Comparable<Long> { }
@link
作用
用于快速跳转到相关代码
用法
{@link 包名.类名#方法名(参数类型)}
当包名在当前类中已经导入了包名可以省略。
可以只是一个类名,也可以是仅仅是一个方法名,也可以是类名.方法名。
使用此文档标记的类或者方法,可用按住Ctrl键+鼠标单击快速跳到相应的类或者方法上。
解析成html其实就是使用包名.类名#方法名(参数类型)
示例
// 完全限定的类名 {@link java.nio.charset.CharsetEncoder} // 省略包名 {@link String} and {@link StringBuilder} // 省略类名,表示指向当前的某个方法 {@link #equals(Object)} // 包名.类名#方法名(参数类型) {@link java.lang.Long#toString(long)}
@code
作用
将文本标记为code,这样会被解析成text。
将文本标记为代码样式的文本,在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式。
一般在Javadoc中只要涉及到类名或者方法名,都需要使用@code进行标记。
用法
{@code text}
第二段:详细描述
详细描述一般用一段或多段来详细描述类的作用,详细描述中可以使用html标签,如下:
标签 | 描述 |
<p> | 换行 |
<pre> | 保留文本格式,即保留空格和换行符 |
<a> | 超链接 |
<ul> | 列表 |
<i> | 斜体 |
<blockquote> | 标记引用 |
详细描述和概要描述中间通常有一个空行来分割, 实例如下
第三段:文档标注
用于标注作者、创建时间、参阅类等信息。
@param
说明
一般类中支持泛型时会通过@param来解释泛型的类型。
示例
package java.util; /** * @param <E> the type of elements in this list * */ public interface List<E> extends Collection<E> {}
@author
说明
详细描述后面一般使用@author来标记作者,如果一个文件有多个作者来维护就标记多个@author,@author后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址)
示例
// 纯文本作者 @author Rod Johnson // 纯文本作者,邮件 @author Igor Hersht, igorh@ca.ibm.com // 超链接邮件 纯文本作者 @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a> // 纯文本邮件 @author shane_curcuru@us.ibm.com // 纯文本 组织 @author Apache Software Foundation // 超链接组织地址 纯文本组织 @author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>
@see
说明
@see 一般用于标记该类相关联的类。@see即可以用在类上,也可以用在方法上。
示例
/** * @see IntStream * @see LongStream * @see DoubleStream * @see <a href="package-summary.html">java.util.stream</a> * / public interface Stream<T> extends BaseStream<T, Stream<T>> {}
@since
说明
@since 一般用于标记文件创建时项目当时对应的版本,一般后面跟版本号,也可以跟是一个时间,表示文件当前创建的时间。
示例
package java.util.stream; /** * @since 1.8 */ public interface Stream<T> extends BaseStream<T, Stream<T>> {}
package org.springframework.util; /** * @since 16 April 2001 */ public abstract class StringUtils {}
@version 版本
作用
@version用于标记当前版本,默认为1.0
示例
package com.sun.org.apache.xml.internal.resolver; /** * @version 1.0 */ public class CatalogManager {}
写在方法上的JavaDoc
写在方法上的文档标注一般分为三段:
- 第一段:概要描述
- 通常用一句或者一段话简要描述该方法的作用,以英文句号作为结束
- 第二段:详细描述
- 通常用一段或者多段话来详细描述该方法的作用,一般每段话都以英文句号作为结束
- 第三段:文档标注
- 用于标注参数、返回值、异常、参阅等
第一段:概要描述
与上边的相同: “写在类上面的JavaDoc” => 第一段:概要描述
第二段:详细描述
与上边的相同: “写在类上面的JavaDoc” => 第二段:详细描述
第三段:文档标注
@param
说明
@param 后面跟参数名,再跟参数描述。
示例
/** * @param str the {@code CharSequence} to check (may be {@code null}) */ public static boolean hasText(@Nullable CharSequence str) { return (str != null && str.length() > 0 && containsText(str)); }
@return
说明
@return 跟返回值的描述
示例
/** * @return {@code true} if the {@code CharSequence} is not {@code null}, * its length is greater than 0, and it does not contain whitespace only */ public static boolean hasText(@Nullable CharSequence str) { return (str != null && str.length() > 0 && containsText(str)); }
@throws
说明
@throws 异常类型 异常描述 , 用于描述方法内部可能抛出的异常
示例
/** * @throws IllegalArgumentException when the given source contains invalid encoded sequences */ public static String uriDecode(String source, Charset charset) {}
@exception
说明
@exception 用于描述方法签名throws对应的异常
示例
package com.sun.jmx.remote.security; /** * @exception LoginException if the logout fails. */ public boolean logout() throws LoginException {}
@deprecated
说明
@deprecated 用于标注一个类或成员已过期,通常配合{@link}使用
示例
/** * @deprecated as of 5.0.4, in favor of {@link Locale#toLanguageTag()} */ @Deprecated public static String toLanguageTag(Locale locale) { return locale.getLanguage() + (hasText(locale.getCountry()) ? "-" + locale.getCountry() : ""); }
@see
说明
@see 既可以用来类上也可以用在方法上,表示可以参考的类或者方法
示例
/** * @see java.net.URLDecoder#decode(String, String) */ public static String uriDecode(String source, Charset charset) {}
@value
说明
{@value} 用于标注在常量上用于表示常量的值。
简介
/** 默认数量 {@value} */ private static final Integer QUANTITY = 1;
@inheritDoc
说明
@inheritDoc 用于注解在重写方法或者子类上,用于继承父类中的Javadoc
- 基类的文档注释被继承到了子类
- 子类可以再加入自己的注释(特殊化扩展)
- @return @param @throws 也会被继承
JavaDoc示例
spring-core中的StringUtils
package org.springframework.util; /** * Miscellaneous {@link String} utility methods. * * <p>Mainly for internal use within the framework; consider * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a> * for a more comprehensive suite of {@code String} utilities. * * <p>This class delivers some simple functionality that should really be * provided by the core Java {@link String} and {@link StringBuilder} * classes. It also provides easy-to-use methods to convert between * delimited strings, such as CSV strings, and collections and arrays. * * @author Rod Johnson * @author Juergen Hoeller * @author Keith Donald * @author Rob Harrop * @author Rick Evans * @author Arjen Poutsma * @author Sam Brannen * @author Brian Clozel * @since 16 April 2001 */ public abstract class StringUtils { /** * Check that the given {@code CharSequence} is neither {@code null} nor * of length 0. * <p>Note: this method returns {@code true} for a {@code CharSequence} * that purely consists of whitespace. * <p><pre class="code"> * StringUtils.hasLength(null) = false * StringUtils.hasLength("") = false * StringUtils.hasLength(" ") = true * StringUtils.hasLength("Hello") = true * </pre> * @param str the {@code CharSequence} to check (may be {@code null}) * @return {@code true} if the {@code CharSequence} is not {@code null} and has length * @see #hasText(String) */ public static boolean hasLength(@Nullable CharSequence str) { return (str != null && str.length() > 0); } }
请先
!