11.05 javadov的初步了解 （一个吃太多想吐的周二下午）

什么是javadoc：

Javadoc的作用是针对整个方法或者整个类做一个简要的概述，使得别人不通过看具体方法代码就能知道某个方法或者某个类的作用和功能。写了Javadoc的在别人使用到类时，将鼠标悬停到类上或者方法上，javadoc会以提示信息显示出来，这样开发者在跳进源代码中就能知道类或者方法的作用.

Javadoc 基本使用

第一段：概要描述

1. @link：{@link 包名.类名#方法名(参数类型)} 用于快速链接到相关代码

// 完全限定的类名
{@link java.util.Scanner}

// 省略包名
{@link String}

// 省略类名，表示指向当前的某个方法
{@link #length()}

// 包名.类名.方法名(参数类型)
{@link java.lang.String#charAt(int)}

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

第二段：详细描述
描述类的作用

3. @para
一般类中支持泛型时会通过@param来解释泛型的类型 （其实我没看懂，o(￣︶￣)o）

4. @author
很显然就是标记作者是谁

5. @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>> {}

6. @since 从以下版本开始
@since 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间（感觉我们平时用不到呢）

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

三：写在方法上的Javadoc

8. @param

@param 后面跟参数名，再跟参数描述

/**
* @param str the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}

9. @return（对返回值的描述）
@return 跟返回值的描述

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

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

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

11. @exception（？）
用于描述方法签名throws对应的异常

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

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

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

13. @value（值）
用于标注在常量上，{@value} 用于表示常量的值

/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;

14. @inheritDoc
@inheritDoc用于注解在重写方法或者子类上，用于继承父类中的Javadoc

1.基类的文档注释被继承到了子类
2.子类可以再加入自己的注释（特殊化扩展）
3.@return @param @throws 也会被继承