code开发java x javadoc @code

转载

mob6454cc67554d 2023-07-11 10:42:44

文章标签 code开发java x java 类名泛型 文章分类 Java 后端开发

基础知识

JavaDoc主要描述类和方法的作用，为以后作参考。
JavaDoc注释写法为：

/** 注释内容 */   [跟java注释/* 注释内容*/ 不同]

JavaDoc中可以使用html标签，如p，pre，a，ul，i等。

文档标记

@开头的，是JDK预先定义好的。

@link：快速链接代码，使用之后可以ctrl+单机快速跳转到相应的类或者方法。完整形态：{@link 包名.类名#方法名(参数类型)}
// 完全限定的类名
{@link java.lang.Character }
// 如果此包在当前类中已经导入，那可以省略包名只写类名
{@link String}
// 省略类名，表示指向当前的某个方法
{@link #length()}
// 完整形态
{@link java.lang.String#charAt(int)}
@code：将文本标记为代码样式，这样在code内部使用<>等不会被解析成为html标签。如果在JavaDoc中涉及到类名或者方法名，一般都需要用@code标记
{@code text}
@author：多个作者就多个@author，后面可以跟作者，邮件，链接等
@see：另请参阅相关联的类
@since：标记文件创建时项目当时对应的版本，或者创建时间
@version：标注版本

类上的JavaDoc

包含三段：

第一段：概要描述，一句话描述类的作用，用英文句号结束。
第二段：详细描述，可以多段，每一段用英文句号结束。一般以< p >开始，与概要描述之间隔一个空行。涉及类名和方法名用@code标记，涉及到组织，用a标签提供链接。
如果类中支持泛型，需要用@param来解释泛型的类型

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

第三段：文档标注，如作者，创建时间，参阅类等

方法上的JavaDoc

包含三段：

第一段：概要描述，一句话简述作用，英文句号结束
第二段：详细描述作用，英文句号结束。
第三段：文档标注，如参数、返回值、异常、参阅
详细描述中常使用html标签，通常以p标签开始，但是这个p标签一般是单标签，不使用结束标签。

<pre>中的文本会保留空格和换行符，文本本身也是等宽的，所以一般用于表示源代码，如举例如何使用方法
<pre>中如果有小于号，大于号（比如泛型），生成javadoc时会报错
一般<p>经常结合<pre>，<pre>也常结合@code

@param 后跟参数名，再跟参数描述
@return 跟返回值的描述

@throws 跟异常类型  +描述什么情况下抛出这个异常
@exception描述@throws对应的异常

@see 参阅什么类或者方法，不需要跟{@link }，直接@see java.net.URLDecoder#decode(String, String)

@value 标注在常量上

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

@return @param @throws 也会被继承