Java文档注释用法+JavaDoc的使用说明

2023-08-17 来源：易榕旅网

Java⽂档注释⽤法+JavaDoc的使⽤说明

简介

⽂档注释负责描述类、接⼝、⽅法、构造器、成员属性。可以被JDK提供的⼯具 javadoc 所解析，⾃动⽣成⼀套以⽹页⽂件形式体现该程序说明⽂档的注释。注意：⽂档注释必须写在类、接⼝、⽅法、构造器、成员字段前⾯，写在其他位置⽆效。

写在类上⾯的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}. *

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}. *

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 Hacker's * Delight, (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 {}

在注释中出现以@开头的东东被称之为Javadoc⽂档标记，是JDK定义好的如@author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws等。@link：{@link 包名.类名#⽅法名(参数类型)} ⽤于快速链接到相关代码

@link的使⽤语法{@link 包名.类名#⽅法名(参数类型)}，其中当包名在当前类中已经导⼊了包名可以省略，可以只是⼀个类名，也可以是仅仅是⼀个⽅法名，也可以是类名.⽅法名，使⽤此⽂档标记的类或者⽅法，可⽤按住Ctrl键+⿏标单击快速跳到相应的类或者⽅法上，解析成html其实就是使⽤包名.类名#⽅法名(参数类型)@link⽰例

// 完全限定的类名

{@link java.nio.charset.CharsetEncoder}// 省略包名

{@link String} and {@link StringBuilder}// 省略类名，表⽰指向当前的某个⽅法{@link #equals(Object)}

// 包名.类名#⽅法名(参数类型)

{@link java.lang.Long#toString(long)}

@code： {@code text} 将⽂本标记为code

@code的使⽤语法{@code text} 会被解析成text

将⽂本标记为代码样式的⽂本，在code内部可以使⽤ < 、> 等不会被解释成html标签, code标签有⾃⼰的样式⼀般在Javadoc中只要涉及到类名或者⽅法名，都需要使⽤@code进⾏标记。

第⼆段：详细描述

详细描述⼀般⽤⼀段或多段来详细描述类的作⽤，详细描述中可以使⽤html标签，如

、

、、、 等标签， 通常详细描述都以段落p标签开始。详细描述和概要描述中间通常有⼀个空⾏来分割， 实例如下package org.springframework.util;/**
* Miscellaneous {@link String} utility methods. *
*
Mainly for internal use within the framework; consider* Apache's Commons Lang * for a more comprehensive suite of {@code String} utilities. *
*
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 {}
⼀般段落都⽤p标签来标记，凡涉及到类名和⽅法名都⽤@code标记，凡涉及到组织的，⼀般⽤a标签提供出来链接地址。@param
⼀般类中⽀持泛型时会通过@param来解释泛型的类型
package java.util;/**
* @param  the type of elements in this list * */
public interface List extends Collection {}
@author
详细描述后⾯⼀般使⽤@author来标记作者，如果⼀个⽂件有多个作者来维护就标记多个@author，@author后⾯可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官⽹地址)
// 纯⽂本作者
@author Rod Johnson// 纯⽂本作者，邮件
@author Igor Hersht, igorh@ca.ibm.com// 超链接邮件 纯⽂本作者
@author Ovidiu Predescu// 纯⽂本邮件
@author shane_curcuru@us.ibm.com// 纯⽂本 组织
@author Apache Software Foundation// 超链接组织地址 纯⽂本组织
@author  Apache Jakarta Turbine
@see 另请参阅
@see ⼀般⽤于标记该类相关联的类,@see即可以⽤在类上，也可以⽤在⽅法上。
/**
* @see IntStream * @see LongStream * @see DoubleStream
* @see java.util.stream * /
public interface Stream extends BaseStream> {}
@since 从以下版本开始
@since ⼀般⽤于标记⽂件创建时项⽬当时对应的版本，⼀般后⾯跟版本号，也可以跟是⼀个时间，表⽰⽂件当前创建的时间
package java.util.stream;/**
* @since 1.8*/
public interface Stream extends BaseStream> {}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
写在⽅法上的⽂档标注⼀般分为三段：
第⼀段：概要描述，通常⽤⼀句或者⼀段话简要描述该⽅法的作⽤，以英⽂句号作为结束
第⼆段：详细描述，通常⽤⼀段或者多段话来详细描述该⽅法的作⽤，⼀般每段话都以英⽂句号作为结束第三段：⽂档标注，⽤于标注参数、返回值、异常、参阅等
⽅法详细描述上经常使⽤html标签，通常都以p标签开始，⽽且p标签通常都是单标签，不使⽤结束标签，其中使⽤最多的就是p标签和pre标签,ul标签, i标签。
pre标签可定义预格式化的⽂本。被包围在pre标签中的⽂本通常会保留空格和换⾏符。⽽⽂本也会呈现为等宽字体，pre标签的⼀个常见应⽤就是⽤来表⽰计算机的源代码。⼀般p经常结合pre使⽤，或者pre结合@code共同使⽤(推荐@code⽅式)⼀般经常使⽤pre来举例如何使⽤⽅法
注意：pre标签中如果有⼩于号、⼤于号、例如泛型 在⽣产javadoc时会报错p结合pre使⽤
/**
* Check that the given {@code CharSequence} is neither {@code null} nor * of length 0.
*
Note: this method returns {@code true} for a {@code CharSequence} * that purely consists of whitespace. *
* StringUtils.hasLength(null) = false * StringUtils.hasLength(\"\") = false * StringUtils.hasLength(\" \") = true
* StringUtils.hasLength(\"Hello\") = true * 
* @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);}
pre结合@code使⽤
{@codePerson[] men = people.stream()
.filter(p -> p.getGender() == MALE)                        .toArray(Person[]::new);}
@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 也会被继承
⽰例
spring-core中的StringUtils ⽰例
package org.springframework.util;/**
* Miscellaneous {@link String} utility methods. *
*
Mainly for internal use within the framework; consider
* Apache's Commons Lang * for a more comprehensive suite of {@code String} utilities. *
*
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.
*
Note: this method returns {@code true} for a {@code CharSequence}  * that purely consists of whitespace.  *
* StringUtils.hasLength(null) = false  * StringUtils.hasLength(\"\") = false  * StringUtils.hasLength(\" \") = true  * StringUtils.hasLength(\"Hello\") = true  * 
* @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); }}
亲⾃实践
package com.example.javadocdemo;import java.math.BigDecimal;import java.util.Objects;/**
* 类 {@code OrderService} 订单服务层. *
*
主要包括 创建订单、取消订单、查询订单等功能更 *
* @see Order
* @author Lerry Li * @since 2019/05/06 */
public class OrderService {    /** 默认数量 {@value} */
private static final Integer QUANTITY = 1;    /**
* 创建订单.     *
*
创建订单需要传⽤户id和商品列表(商品id和商品数量).     *
* 
{@code*  演⽰如何使⽤该⽅法
*  List items = new ArrayList<>();
*  Goods goods = new Goods(1L, BigDecimal.ONE);     *  Goods goods2 = new Goods(2L, BigDecimal.TEN);     *  items.add(goods);     *  items.add(goods2);     *
*  Order order1 = new Order();     *  order.setUserId(\"1\");     *  order.setItems(items);
*  OrderService#createOrder(order);     * }
* 
     ** @param order 订单信息
* @throws NullPointerException 参数信息为空
* @exception IllegalArgumentException  数量不合法     * @return 是否创建成功     * @version 1.0     * @see Order     */
public boolean createOrder(Order order) throws IllegalArgumentException{        Objects.requireNonNull(order);
List items = order.getItems();        items.forEach(goods -> {
BigDecimal quantity = goods.getQuantity();
if (quantity == null || BigDecimal.ZERO.compareTo(quantity) == 0) {                throw new IllegalArgumentException();            }        });
System.out.println(\"create order...\");        return true;    }}
⽣成JavaDoc
通过IDEA⽣成Javadoc： Tools –> Generate JavaDoc
注意要配置编码，如果不配置则⽣成的JavaDoc会乱码，还需要配置Output directory
这⾥有⼏点要特别注意⼀下：
1、IDEA 的 JavaDoc ⽣成功能在菜单 Tools->Generate JavaDoc 项⾥⾯。
2、点击上述菜单项后，会出现⽣成 JavaDoc 的对话框，⼀般的选项都很直观，不必细说。但是要注意⽣成 JavaDoc 的源代码对象的选择，⼀般以模块（Module）为主，必要时可以单独选择必要的 Java 源代码⽂件，不推荐以 Project 为 JavaDoc ⽣成的源范围。
3、⾥⾯有⼀个 Locale 可选填项，表⽰的是需要⽣成的 JavaDoc 以何种语⾔版本展⽰，根据 javadoc.exe 的帮助说明，这其实对应的就是 javadoc.exe 的 -locale 参数，如果不填，默认可能是英⽂或者是当前操作系统的语⾔，既然是国⼈，建议在此填写 zh_CN，这样⽣成的 JavaDoc 就是中⽂版本的，当然指的是 JavaDoc 的框架中各种通⽤的固定显⽰区域都是中⽂的。你⾃⼰编写的注释转换的内容还是根据你注释的内容来。
4、还有⼀个“Other command line arguments:”可选填项，⾮常重要，是填写直接向 javadoc.exe 传递的参数内容。因为有⼀些重要的设置，只能通过直接参数形式向 javadoc.exe 传递。这⾥必须要填写如下参数：
5、第⼀个参数 -encoding UTF-8 表⽰你的源代码（含有符合 JavaDoc 标准的注释）是基于 UTF-8 编码的，以免处理过程中出现中⽂等⾮英语字符乱码；第⼆个参数 -charset UTF-8 表⽰在处理并⽣成 JavaDoc 超⽂本时使⽤的字符集也是以 UTF-8 为编码，⽬前所有浏览器都⽀持 UTF-8，这样最具有通⽤性，⽀持中⽂⾮常好；第三个参数 -windowtitle 表⽰⽣成的
JavaDoc 超⽂本在浏览器中打开时，浏览器窗⼝标题栏显⽰的⽂字内容；第四个参数 -link 很重要，它表⽰你⽣成的 JavaDoc 中涉及到很多对其他外部 Java 类的引⽤，是使⽤全限定名称还是带有超链接的短名称
-link 实质上是告诉 javadoc.exe 根据提供的外部引⽤类的 JavaDoc 地址去找⼀个叫 package-list 的⽂本⽂件，在这个⽂本⽂件中包含了所有外部引⽤类的全限定名称，因此⽣成的新JavaDoc 不必使⽤外部引⽤类的全限定名，只需要使⽤短名称，同时可以⾃动创建指向其外部引⽤ JavaDoc 中的详细⽂档超链接。每个 JavaDoc 都会在根⽬录下有⼀个 package-list ⽂件，包括我们⾃⼰⽣成的 JavaDoc。
查看成果
配置完毕后点击OK按钮,console看到如下⽇志输出则说明JavaDoc⽣成成功
JavaDoc ⽣成完毕，即可在其根⽬录下找到 index.html ⽂件，打开它就可以看到我们⾃⼰的标准 JavaDoc API ⽂档啦。
以上为个⼈经验，希望能给⼤家⼀个参考，也希望⼤家多多⽀持。
        

		
			因篇幅问题不能全部显示，请点此查看更多更全内容
			查看全文

全部栏目

Java文档注释用法+JavaDoc的使用说明