Javadoc 具体使用详解

2023-07-19 01:05:03 330

很多程序对Javadoc都不重视，认识不到Javadoc的作用，很多人都是这样认为的：“我只要写好功能就够了，写Javadoc太浪费时间，也没啥作用，还不如用写Javadoc的时间再多些个功能呢！”，我们知道注释是为了解释代码的作用的，是为了将来给自己或者别人快速了解代码的，在方法内一般用行注释//的比较多，是针对一小块代码做出解释的，而Javadoc的作用是针对整个方法或者整个类做一个简要的概述的，使得别人不通过看具体方法代码就能知道某个方法或者某个类的作用和功能。写了Javadoc的在别人使用到类时，将鼠标悬停到类上或者方法上，javadoc会以提示信息显示出来，这样开发者在跳进源代码中就能知道类或者方法的作用。说到这里可能还是有很多人不能认同这种观点，还是认识不到Javadoc的作用。我们看一下Spring框架，随便打开一个文件可以看到一般注释内容都要比代码量多，有的时候注释量占整个文件内容的2/3。有人还是认为Spring是大框架，每个Java项目都在用他们写的好事应该的，我们公司自己的项目就我们公司几个人看，没必要花时间去写多余的Javadoc，那你是不是该这么认为了Spring大厂中的顶尖大牛都这么做，我们小菜鸟是不是对自己要求更严格一些，向大牛去学习呢？！假如在公司A程序员写了Javadoc，B程序员只写功能不写Javadoc不写注释，那么一般会认为A程序员会比B程序员做的好。认识不到Javadoc的作用就像认识不到设计模式的作用一样，很多人都认识不到设计模式的作用，认为将简单问题复杂化，你看一下每个大框架都会用到多种设计模式，如果只知道写增删改查，再工作几年仍然不会有提高。

一：简介

Javadoc用于描述类或者方法的作用。Javadoc可以写在类上面和方法上面。

https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html

二：写在类上面的Javadoc

写在类上的文档标注一般分为三段：

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注作者、创建时间、参阅类等信息

第一段：概要描述

单行示例：

packageorg.springframework.util;
/**
*Miscellaneous{@linkString}utilitymethods.
*
*/
publicabstractclassStringUtils{

多行示例：

packagejava.lang;

/**
*Class{@codeObject}istherootoftheclasshierarchy.
*Everyclasshas{@codeObject}asasuperclass.Allobjects,
*includingarrays,implementthemethodsofthisclass.
*/
publicclassObject{}

在注释中出现以@开头东东被称之为Javadoc文档标记，是JDK定义好的，如@author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws等。

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

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

@link示例

//完全限定的类名
{@linkjava.lang.Character}

//省略包名
{@linkString}

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

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

2.@code：{@codetext}将文本标记为code

{@codetext}会被解析成text
将文本标记为代码样式的文本，在code内部可以使用<、>等不会被解释成html标签,code标签有自己的样式

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

第二段：详细描述

详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用html标签，如

、

、、、等标签，通常详细描述都以段落p标签开始。

详细描述和概要描述中间通常有一个空行来分割
packageorg.springframework.util;

/**
*Miscellaneous{@linkString}utilitymethods.
*
*Mainlyforinternalusewithintheframework;consider
*Apache'sCommonsLang
*foramorecomprehensivesuiteof{@codeString}utilities.
*
*
Thisclassdeliverssomesimplefunctionalitythatshouldreallybe
*providedbythecoreJava{@linkString}and{@linkStringBuilder}
*classes.Italsoprovideseasy-to-usemethodstoconvertbetween
*delimitedstrings,suchasCSVstrings,andcollectionsandarrays.
*
*/
publicabstractclassStringUtils{


一般段落都用p标签来标记，凡涉及到类名和方法名都用@code标记，凡涉及到组织的，一般用a标签提供出来链接地址。
3.@param
一般类中支持泛型时会通过@param来解释泛型的类型
/**
*@paramthetypeofelementsinthislist
*/
publicinterfaceListextendsCollection{}
4.@author
详细描述后面一般使用@author来标记作者，如果一个文件有多个作者来维护就标记多个@author，@author后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址)
//纯文本作者
@authorRodJohnson

//纯文本作者，邮件
@authorIgorHersht,igorh@ca.ibm.com

//超链接邮件纯文本作者
@authorOvidiuPredescu

//纯文本邮件
@authorshane_curcuru@us.ibm.com

//纯文本组织
@authorApacheSoftwareFoundation

//超链接组织地址纯文本组织
@authorApacheJakartaTurbine
5.@see另请参阅
@see一般用于标记该类相关联的类,@see即可以用在类上，也可以用在方法上。
/**
*@seeIntStream
*@seeLongStream
*@seeDoubleStream
*@seejava.util.stream
*/
publicinterfaceStreamextendsBaseStream>{}
6.@since从以下版本开始
@since一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间
packagejava.util.stream;

/**
*@since1.8
*/
publicinterfaceStreamextendsBaseStream>{}

packageorg.springframework.util;

/**
*@since16April2001
*/
publicabstractclassStringUtils{}

7.@version版本
@version用于标记当前版本，默认为1.0
packagecom.sun.org.apache.xml.internal.resolver;
/**
*@version1.0
*/
publicclassResolverextendsCatalog{}

三：写在方法上的Javadoc
写在方法上的文档标注一般分为三段：

第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注参数、返回值、异常、参阅等

方法详细描述上经常使用html标签来，通常都以p标签开始，而且p标签通常都是单标签，不使用结束标签，其中使用最多的就是p标签和pre标签,ul标签,i标签。
pre元素可定义预格式化的文本。被包围在pre元素中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体，pre标签的一个常见应用就是用来表示计算机的源代码。
一般p经常结合pre使用，或者pre结合@code共同使用(推荐@code方式)

一般经常使用pre来举例如何使用方法
注意：pre>标签中如果有小于号、大于号、例如泛型在生产javadoc时会报错
/**
*Checkwhetherthegiven{@codeCharSequence}containsactualtext.
*Morespecifically,thismethodreturns{@codetrue}ifthe
*{@codeCharSequence}isnot{@codenull},itslengthisgreaterthan
*0,anditcontainsatleastonenon-whitespacecharacter.
*

*StringUtils.hasText(null)=false
*StringUtils.hasText("")=false
*StringUtils.hasText("")=false
*StringUtils.hasText("12345")=true
*StringUtils.hasText("12345")=true
*
*@paramstrthe{@codeCharSequence}tocheck(maybe{@codenull})
*@return{@codetrue}ifthe{@codeCharSequence}isnot{@codenull},
*itslengthisgreaterthan0,anditdoesnotcontainwhitespaceonly
*@seeCharacter#isWhitespace
*/
publicstaticbooleanhasText(@NullableCharSequencestr){
	return(str!=null&&str.length()>0&&containsText(str));
}

{@code Person[]men=people.stream() .filter(p->p.getGender()==MALE) .toArray(Person[]::new); }

8.@param

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

/** *@paramstrthe{@codeCharSequence}tocheck(maybe{@codenull}) */ publicstaticbooleancontainsWhitespace(@NullableCharSequencestr){}

9.@return

@return跟返回值的描述

/** *@return{@codetrue}ifthe{@codeString}isnot{@codenull},its */ publicstaticbooleanhasText(@NullableStringstr){}

10.@throws

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

/** *@throwsIllegalArgumentExceptionwhenthegivensourcecontainsinvalidencodedsequences */ publicstaticStringuriDecode(Stringsource,Charsetcharset){}

11.@exception

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

/** *@exceptionIllegalArgumentExceptionifkeyisnull. */ publicstaticObjectget(Stringkey)throwsIllegalArgumentException{}

12.@see

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

/** *@exceptionIllegalArgumentExceptionifkeyisnull. */ publicstaticObjectget(Stringkey)throwsIllegalArgumentException{}

13.@value

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

/**默认数量{@value}*/ privatestaticfinalIntegerQUANTITY=1;

14.@inheritDoc

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

基类的文档注释被继承到了子类

子类可以再加入自己的注释（特殊化扩展）

@return@param@throws也会被继承

四：示例

spring-core中的StringUtils示例

packageorg.springframework.util; /** *Miscellaneous{@linkString}utilitymethods. * *
Mainlyforinternalusewithintheframework;consider *Apache'sCommonsLang *foramorecomprehensivesuiteof{@codeString}utilities. * *
Thisclassdeliverssomesimplefunctionalitythatshouldreallybe *providedbythecoreJava{@linkString}and{@linkStringBuilder} *classes.Italsoprovideseasy-to-usemethodstoconvertbetween *delimitedstrings,suchasCSVstrings,andcollectionsandarrays. * *@authorRodJohnson *@authorJuergenHoeller *@authorKeithDonald *@authorRobHarrop *@authorRickEvans *@authorArjenPoutsma *@authorSamBrannen *@authorBrianClozel *@since16April2001 */ publicabstractclassStringUtils{ /** *DecodethegivenencodedURIcomponentvalue.Basedonthefollowingrules: *
*
Alphanumericcharacters{@code"a"}through{@code"z"},{@code"A"}through{@code"Z"}, *and{@code"0"}through{@code"9"}staythesame.
*
Specialcharacters{@code"-"},{@code"_"},{@code"."},and{@code"*"}staythesame.
*
Asequence"{@code%xy}"isinterpretedasahexadecimalrepresentationofthecharacter.
*
* *@paramsourcetheencodedString *@paramcharsetthecharacterset *@returnthedecodedvalue *@throwsIllegalArgumentExceptionwhenthegivensourcecontainsinvalidencodedsequences *@since5.0 *@seejava.net.URLDecoder#decode(String,String) */ publicstaticStringuriDecode(Stringsource,Charsetcharset){}

packagecom.example.demo; /** *类{@codeOrderService}订单服务层. * *
主要包括创建订单、取消订单、查询订单等功能更 * *@seeOrder *@authorMengdayZhang *@since2018/5/12 */ publicclassOrderService{ /**默认数量{@value}*/ privatestaticfinalIntegerQUANTITY=1; /** *创建订单. * *
创建订单需要传用户id和商品列表(商品id和商品数量). * *
{@code *演示如何使用该方法 *Listitems=newArrayList<>(); *Goodsgoods=newGoods(1L,BigDecimal.ONE); *Goodsgoods2=newGoods(2L,BigDecimal.TEN); *items.add(goods); *items.add(goods2); * *Orderorder1=newOrder(); *order.setUserId("1"); *order.setItems(items); *OrderService#createOrder(order); *} *
* *@paramorder订单信息 *@throwsNullPointerException参数信息为空 *@exceptionIllegalArgumentException数量不合法 *@return是否创建成功 *@version1.0 *@see{@linkOrder} */ publicbooleancreateOrder(Orderorder)throwsIllegalArgumentException{ Objects.requireNonNull(order); Listitems=order.getItems(); items.forEach(goods->{ BigDecimalquantity=goods.getQuantity(); if(quantity==null||BigDecimal.ZERO.compareTo(quantity)==0){ thrownewIllegalArgumentException(); } }); System.out.println("createorder..."); returntrue; } }

五：生成Javadoc

idea生成javadochttps://www.nhooo.com/article/192943.htm

通过IDEA生成Javadoc：Tools-->GenerateJavaDoc-->
注意要配置编码，如果不配送为生成乱码，还需要配置Outputdirectory

到此这篇关于Javadoc具体使用详解的文章就介绍到这了,更多相关Javadoc使用内容请搜索毛票票以前的文章或继续浏览下面的相关文章希望大家以后多多支持毛票票！
声明：本文内容来源于网络，版权归原作者所有，内容由互联网用户自发贡献自行上传，本网站不拥有所有权，未作人工编辑处理，也不承担相关法律责任。如果您发现有涉嫌版权的内容，欢迎发送邮件至：czq8825#qq.com（发邮件时，请将#更换为@）进行举报，并提供相关证据，一经查实，本站将立刻删除涉嫌侵权内容。

上一篇
Idea 2020.2 创建web、Spring项目的教程图解下一篇
Python Celery异步任务队列使用方法解析

热门推荐

1 毛坯房验收经验和常识看了之后再验房心里有底

2 二手房收房如何交接二手房收房注意问题

3 专业验收毛坯房的价格商品房验收合格的标准

4 精装房怎么验收精装房请验房师有用吗

5 一般要到哪里找验房师验房师有哪些作用呢

6 请人验房一般是多少钱验房师费用是多少

7 怎样测量房子面积建筑面积和使用面积怎么算

8 收房需要注意什么仔细检查不松懈

9 收房时三书一证一表是什么主要作用介绍

10 交房时交房税费有哪些本文为你一一讲解

11 验房都需要验什么要做哪些准备呢

12 毛坯房验房师有必要请吗毛坯房装修完如何验收

13 地下室防水工程质量验收规范详解

14 水性涂料、油性涂料区别介绍

15 零基础布艺DIY工坊教你做超萌猫头鹰钥匙包

16 三棵树漆怎么样？三棵树漆官方网站

17 家庭“装修套餐”中猫腻你知道吗？

18 小空间大浴望卫浴间装修巧支招

Javadoc 具体使用详解

热门推荐

随机推荐