什么是javadoc
javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档了。
(API文档:API是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。API文档是API的说明文档,也称为帮助文档。)
Javadoc用于描述类或者方法的作用。Javadoc可以写在类上面和方法上面。
javadoc标签
标签 | 说明 |
@author | 作者标识 |
@version | 版本号 |
@param | 方法的入参名及描述信息 |
@return | 对函数返回值的注释 |
@deprecated | 过期文本 |
@throws | 构造函数或方法所会抛出的异常 |
@exception | 同@throws |
@see | 查看相关内容,如类、方法、变量等 |
@since | API在什么程序的什么版本后开发支持 |
{@link包.类#成员 标签} | 链接到某个特定的成员对应的文档中 |
{@value} | 当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值 |
javadoc基本使用规范
1. 写在类上的Javadoc:
写在类上的文档标注一般分为三段:
第一段:概要描述,通常用一句或者一段话简要描述该类的作用,以英文句号 作为结束
第二段:详细描述,通常用一段或者多段话来详细描述该类的作用,一般每段话都以英文句号作为结束
第三段:文档标注,用于标注作者、创建时间、参阅类等信息
2.写在方法上的javadoc
写在方法上的文档标注一般分为三段:
第一段:概要描述,通常用一句或者一段话简要描述该方法的作用,以英文句号作为结束
第二段:详细描述,通常用一段或者多段话来详细描述该方法的作用,一般每段话都以英文句号作为结束
第三段:文档标注,用于标注参数、返回值、异常、参阅等
方法详细描述上经常使用html标签来,通常都以p标签开始,而且p标签通常都是单标签,不使用结束标签,其中使用最多的就是p标签和pre标签,ul标签, i标签。