输出文档之注释

Posted 2021-02-10 zbb2161228

俗话说，代码千万行，注释第一行。

又有俗话说，程序员最讨厌的四件事：写注释、写文档、别人不写注释、别人不写文档。

还听说，美国一程序员因不写注释被同事枪杀。。。

写好每一行注释从你我做起（立个flag）

//单行注释

/* 单行或多行注释 */

/**
*用于输出javadoc的注释形式
*/

JavaDoc常见参数：

官方描述：
https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html

@link的使用语法{@link 包名.类名#方法名(参数类型)}，其中当包名在当前类中已经导入了包名可以省略，可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名.方法名，使用此文档标记的类或者方法，可用通过按住Ctrl键+单击 可以快速跳到相应的类或者方法上
示例：
// 包名.类名.方法名(参数类型)
{@link java.lang.String#charAt(int)}

{@code text} 
一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。

详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用html标签，如<p>、<pre>、<a>、<ul>、<i> 等标签， 通常详细描述都以段落p标签开始。
/**
* 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.
*
*/

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

一般类中支持泛型时会通过@param来解释泛型的类型

/** * @param <E> the type of elements in this list */
public interface List<E> extends Collection<E> {}

详细描述后面一般使用@author来标记作者，如果一个文件有多个作者来维护就标记多个@author，@author 后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址)

@see 一般用于标记该类相关联的类,@see即可以用在类上，也可以用在方法上。

@since 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间

@version 用于标记当前版本，默认为1.0

方法中的：

@param 后面跟参数名，再跟参数描述
/**
* @param str the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}

@return 跟返回值的描述

/**
* @return {@code true} if the {@code String} is not {@code null}, its
*/
public static boolean hasText(@Nullable String str){}

@throws 跟异常类型 异常描述 , 用于描述方法内部可能抛出的异常

/**
* @throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset){}

用于描述方法签名throws对应的异常

/**
* @exception IllegalArgumentException if <code>key</code> is null.
*/
public static Object get(String key) throws IllegalArgumentException {}

@see既可以用来类上也可以用在方法上，表示可以参考的类或者方法

/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}

用于标注在常量上，{@value} 用于表示常量的值
/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;

@inheritDoc用于注解在重写方法或者子类上，用于继承父类中的Javadoc
基类的文档注释被继承到了子类
子类可以再加入自己的注释（特殊化扩展）
@return @param @throws 也会被继承