【摘】Java文档注释用法+JavaDoc的使用详解

=

=

 

节约重复注释

使用@inheritDoc  

使用@see

 

=

 

Java文档注释用法+JavaDoc的使用详解

文档注释负责描述类、接口、方法、构造器、成员属性。可以被JDK提供的工具 javadoc 所解析，自动生成一套以网页文件形式体现该程序说明文档的注释。

注意：文档注释必须写在类、接口、方法、构造器、成员字段前面，写在其他位置无效。

JavaDoc 官方说明
How to Write Doc Comments for the Javadoc Tool

 

原文：https://blog.csdn.net/lsy0903/article/details/89893934

 

一般段落都用p标签来标记，凡涉及到类名和方法名都用@code标记，凡涉及到组织的，一般用a标签提供出来链接地址。

@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, [e-mail]

// 超链接邮件 纯文本作者
@author <a href="mailto:[e-mail]">Ovidiu Predescu</a>

// 纯文本邮件
@author [e-mail]

// 纯文本 组织
@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 {}

 

 

@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 也会被继承

 

 

原文：https://blog.csdn.net/lsy0903/article/details/89893934

 

=

=

=