首页
学习
活动
专区
工具
TVP
发布
精选内容/技术社群/优惠产品,尽在小程序
立即前往

我应该在我的javadoc类和方法注释中写什么?

在JavaDoc类和方法注释中,您应该包括以下内容:

  1. 类和方法的简要描述:简要说明类或方法的作用和功能。
  2. 参数说明:对方法的每个参数进行详细说明,包括参数名称、类型、作用和允许的取值范围。
  3. 返回值说明:对方法返回的值进行说明,包括类型和作用。
  4. 异常处理:说明可能抛出的异常类型和原因,以及如何避免或处理这些异常。
  5. 示例代码:提供一个使用该类或方法的示例代码,以便其他开发人员更好地理解和使用它。

JavaDoc注释的格式如下:

代码语言:txt
复制
/**
 * 类或方法的简要描述
 *
 * @param 参数名 参数类型 参数描述
 * @return 返回值类型 返回值描述
 * @throws 异常类型 异常描述
 */

例如,对于一个计算两个数之和的方法,JavaDoc注释可以如下所示:

代码语言:txt
复制
/**
 * 计算两个数之和
 *
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两个数之和
 */
public int add(int a, int b) {
    return a + b;
}

在JavaDoc注释中,使用"@"符号来标记注释的不同部分,例如"@param"表示参数说明,"@return"表示返回值说明,"@throws"表示异常处理。这些注释可以帮助其他开发人员更好地理解和使用您的代码,提高代码的可维护性和可读性。

页面内容是否对你有帮助?
有帮助
没帮助

相关·内容

java什么叫抽象方法抽象及他们特点

7.何为抽象方法抽象?  马 克 -to -win:方法前有个abstract修饰符,就叫抽象方法前有个abstract修饰符就是抽象,完了,简单就好记。...以下是二者要点:马 克 -to -w in : 1)抽象方法没有函数体。有童鞋说,这有什么意义呢?比如下面的例子,当我们不知道现在是什么车时,你让驾驶(steer)这个方法怎么呢?...这种场合就需要抽象方法。 2)抽象(Veh)子类(Lim)只要不是抽象,马克-to-win:它自己(Lim)或它(Car)必须把那个抽象抽象方法全部实现掉。...3)抽象不能被实例化。字面上好理解,抽象东西那么抽象,看不见摸不着,当然不能被实际具体生成了。还是举上面的例子。...当我们现在连什么车都不知道时,也不知道它是自行车还是豪华轿车时,你让具体地生成这辆车,当然是不可能了。

60430

【Java学习笔记之十八】Javadoc注释用法

Javadoc注释用法 Java 文档 // 注释一行 /* ...... */ 注释若干行 /** ...... */ 注释若干行,并写入 javadoc 文档 通常这种注释多行写法如下:...文档和文档注释格式化 生成文档是 HTML 格式,而这些 HTML 格式标识符并不是 javadoc,而是我们在注释时候写上去。...文档,对于属性方法都是先有一个列表,然后才在后面一个一个详细说明 简述部分写在一段文档注释最前面,第一个点号 (.) 之前 (包括点号)。...换句话说,就是用第一个点号分隔文档注释,之前是简述,之后是第二部分第三部分。 第二部分是详细说明部分。该部分对属性或者方法进行详细说明,在格式上没有什么特殊要求,可以包含若干个点号。...使用 javadoc 标记 javadoc 标记由"@"及其后所跟标记类型专用注释引用组成 javadoc 标记有如下一些: @author 标明开发该类模块作者 @version 标明该类模块版本

1.6K40
  • Java编码规范

    一般概念 n 注释应该增加代码清晰度 n 保持注释简洁 n 在代码之前注释 n 注释出为什么做了一些事,而不仅仅是做了什么 2.2....示范 文档注释 在紧靠接口、、成员函数字段声明前面注释它们。 /** 客户:客户是我们将服务产品卖给的人或机构。*/ C 语言风格 采用 C 语言风格注释去掉不再使用但你仍想保留代码。...proceted、private package 定义成员变量如果名字含义明确的话,可以没有注释。 5) 存取方法设置与获取成员函数) 接下来是变量存取方法。...clone() { try { …… }catch(CloneNotSupportedException e) { …… }} 8) 方法普通成员函数) 下面开始方法: /** * Set...在任何情况下, 超长语句应该在一个逗号或者一个操作符后折行。 一条语句折行后, 应该比原来语句再缩进2个字符。 n {} 对 {} 语句应该单独作为一行。

    90240

    Groovy语法系列教程之注释(一)

    注释 1.1 单行注释 单行注释以//开头,可以在行任何位置使用。 //后面的字符(直到该行末尾)被视为注释一部分。...// 独立单行注释 println("博客:https://shanyshanb.com/") // 此处开始直至行尾注释 1.2 多行注释 多行注释以/*开头,可以在该行任何位置使用。...这些注释与如下概念有关: 类型定义(、接口、枚举、注解) 字段属性定义 方法定义 如果不在上述概念处添加Groovydoc,编译器不会告警。但应该在这些结构之前加上注释。.../** * 注释 */ class Person { /** Person名字 */ String name /** * 创建打招呼方法 *...因此,也可以使用与Javadoc相同标签。 1.4 shebang行 有一种特殊单行注释,通常被UNIX系统称之为shebang行。 它使脚本可以直接从命令行运行。

    1.3K11

    android-代码样式规范

    Javadoc注释,描述或接口作用。 你每个公共方法必须包含一个Javadoc注释,至少有一个句子描述方法作用。这句话应以第三人称描述性动词开始。...如何为javadoc编写注释 [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html] 5.方法...如果您看到旧代码带有@deprecated Javadoc标记,请添加@Deprecated注释。 @Override:当方法从超覆盖声明或实现时,必须使用@Override注释。...例如,如果使用@inheritdocs Javadoc标记,并从(而不是接口)派生,则还必须注释方法@覆盖父方法。...14.将首字母缩略词作为词 将缩写词缩写词作为命名变量,方法单词,以使名称更易读: 由于JDKAndroid代码库在首字母缩略词之间非常不一致,因此几乎不可能与周围代码一致。

    54730

    Java编程规范-注释

    例如,关于相应包 (package) 是如何构建,以及存放在什么目录,不应该包括在注释,对代码 不太明显设计意图进行说明 是应该,但也应该 避免 对一些明显信息进行 重复说明 ,尽量 避免...避免 注释信息代码 过多重复 ; 3、源程序注释率 ( 注释行数占总行数百分比 ) 应该在 30% 以上,不要求每个文件都达到这个要求,这个要求以模块为单位进行度量; 4、短注释可以跟在代码行后面...要求注释,但不强制要求完全按照此规范处理 接口注释使用 javadoc 风格, 置于 class 或者 interface 关键字所在行之前。...方法参数要仔细说明 方法注释使用 javadoc 风格, 置于 方法声明或定义之前。 注释内容:列出方法一句话功能描述、作者、输入参数、输出参数、返回值、异常等。..., 实体用swagger模式也可 类属性注释使用 javadoc 风格,放在属性 定义之前。

    1.1K20

    idea文档注释设置_idea怎么设置注释模板

    大家好,又见面了,是你们朋友全栈君 一、概述 IDEA自带注释模板不是太好用,本人到网上搜集了很多资料系统整理了一下制作了一份比较完整模板来分享给大家,不是专业玩博客这篇文章只是为了让大家省事...TIME}:设置创建用户、创建日期时间,这些事IDEA内置方法,还有一些其他方法在绿色框标注位置,比如你想添加项目名则可以使用{PROJECT_NAME} (4)1.0:设置版本号,一般新创建都是...1.0版本,这里死就可以了 2、效果图展示 三、方法注释模板 1、创建模板 IDEA还没有智能到自动为我们创建方法注释,这就是要我们手动为方法添加注释,使用Eclipse时我们生成注释习惯是 /...:命名为* 因为IDEA生成注释默认方式是:/*+模板名+快捷键(比如若设置模板名为add快捷键用Tab,则生成方式为 /*add+Tab),如果不采用这样生成方式IDEA没有内容方法将不可用,...可以直接复制!可以直接复制!不要再问我为什么都是图片了,留着眼睛干啥?

    6.9K50

    idea文档注释设置_eclipse添加方法注释模板

    一、概述 IDEA自带注释模板不是太好用,本人到网上搜集了很多资料系统整理了一下制作了一份比较完整模板来分享给大家,不是专业玩博客这篇文章只是为了让大家省事。...TIME}:设置创建用户、创建日期时间,这些事IDEA内置方法,还有一些其他方法在绿色框标注位置,比如你想添加项目名则可以使用{PROJECT_NAME} (4)1.0:设置版本号,一般新创建都是...1.0版本,这里死就可以了 2、效果图展示 三、方法注释模板 1、创建模板 IDEA还没有智能到自动为我们创建方法注释,这就是要我们手动为方法添加注释,使用Eclipse时我们生成注释习惯是 /...:命名为* 因为IDEA生成注释默认方式是:/*+模板名+快捷键(比如若设置模板名为add快捷键用Tab,则生成方式为 /*add+Tab),如果不采用这样生成方式IDEA没有内容方法将不可用,...可以直接复制!可以直接复制!不要再问我为什么都是图片了,留着眼睛干啥?

    3.9K10

    备注应用-注释

    1、注释 1.1、什么注释 用来解释说明程序文字。案例代码我们并不知道什么意思,我们可以使用注释来提醒自己代码功能是什么注释是不会被执行。...(2)对于文档注释,是java特有的注释,其中注释内容可以被JDK提供工具 javadoc 所解析,生成一套以网页文件形式体现该程序说明文档。...在文档注释可以使用注解配合javadoc完成对信息进一步说明。 (3)注释是一个程序员必须要具有的良好编程习惯。便于自己日后代码维护,也方便别人阅读你代码。...:返回值类型,现为固定写法 main:方法名,现为固定写法 String[]:参数类型,现为固定写法 args:参数名,可以自定义修改,建议固定为args */ public class HelloWorld...; } } 注意: 单行注释多行注释都是根据实际注释内容长度来进行声明

    41010

    Java三种注释

    2、多行注释 包含在“/*”“*/”之间,能注释很多行内容。为了可读性比较好,一般首行尾行不注释信息(这样也比较美观好看),如图所示。...注释后,鼠标放在变量上面会自动显示出我们注释内容,如图所示。 注意:文档注释能嵌套单行注释,不能嵌套多行注释和文档注释,一般首行尾行也不注释信息。...文档注释以/**开头,并以*/结束,可以通过 Javadoc 生成 API 帮助文档,Java 帮助文档主要用来说明、成员变量方法功能。...文档注释只放在、接口、成员变量、方法之前,因为 Javadoc 只处理这些地方文档注释,而忽略其它地方文档注释。...Javadoc 是 Sun 公司提供一种工具,它可以从程序源代码抽取方法、成员等注释,然后形成一个源代码配套 API 帮助文档。

    81010

    手写Swagger注解、JavaDoc一键生成插件,生产力拉满~

    但是如果要删除整个中所有的JavaDoc注释、注解,还是使用插件效率更高: 除了对POJO字段进行操作外,也可以将光标指向Controller方法名,指向POJO名,选择相应功能即可对指定元素进行处理...实际原理还是很简单,过程看起来繁琐,但是执行效率极高哦,监控过耗时,大概率不会超过1毫秒。 「填充」「重新生成」区别 插件每个功能都有多个选项,填充、重新生成、合并,他们有什么区别呢?...填充: 当前「、字段、方法已经存在指定「注解、注释」时,不会再重新生成相应「注解、注释」。...重新生成: 不管当前「、字段、方法是否已经存在指定「注解、注释」,会将已存在「注解、注释」直接删除,然后再重新生成相应「注解、注释」。...合并: 当前「、字段、方法如果已经存在指定JavaDoc注释,还是会重新生成新JavaDoc注释,并将其合并到原先JavaDoc中一起展示,新、老JavaDoc注释都会保留哦。

    14110

    Java 异常处理 9 个最佳实践

    在 Java ,异常处理是个很麻烦事情。初学者觉得它很难理解,甚至是经验丰富开发者也要花费很长时间决定异常是要处理掉抛出。 所以很多开发团队约定一些原则处理异常。...3、记录指定异常 每当你在方法签名中指定异常,你也应该在 Javadoc 记录它。 这与上一个最佳实践具有相同目标:尽可能多地向调用者提供信息,以便避免或处理异常。...因此,请确保向 Javadoc 添加 @throws 声明并描述可能导致异常情况。 ? 4、使用描述性消息抛出异常 这个最佳实践背后想法与前两个类似。但这一次,你不会将信息提供给方法调用者。...每个必须了解在日志文件或监视工具中报告异常情况时发生了什么情况的人都可以读取异常消息。 因此,应该尽可能精确地描述问题,并提供最相关信息来了解异常事件。 不要误会意思,你不用去一段文字。...6、不要捕获 Throwable Throwable 是所有异常错误。你可以在 catch 子句中使用它,但是你永远不应该这样做!

    80290

    Effective-java-读书笔记之方法

    第49条 检查参数有效性方法参数限制, 应该在文档中指明, 并且在方法开头处检查参数, 以强制施加这些限制.对于公有的方法, 要用Javadoc@throws标签在文档说明违反参数值限制时会抛出异常...构造函数, 方法字段声明之前加上doc注释.方法文档注释应该简洁地描述出它客户端之间约定....这个约定应该说明这个方法做了什么, 而不是如何完成这项工作.方法文档注释还应该列举出:所有前提条件.....Java 8新增@implSpec: 描述方法子类关系.Java 9Javadoc utility会忽略@implSpec, 除非你在命令行加上"implSpec:a:Implementation...偶尔你需要用{@index}加入额外index.泛型, 枚举, 注解都需要额外注意: 当为泛型方法文档时, 需要为每个泛型参数文档注释.枚举需要为每个常量注释.注解需要注释每个成员.

    42650

    Java基础系列(十一):注释

    前言 曾经看到过一句话:“最烦就是注释看不注释代码”,也许有玩笑成分在,但是不可否认是,注释对于代码来说,是必不可少,它可以大大增加代码可读性,好注释就像好看皮囊,让人赏心悦目...: 包 公有接口 公有的受保护构造器及方法 公有的受保护注释格式是以 /**开始,并以 */结束,每个 /**......包与概述注释 如果想要产生包注释,不能使用上面说那个方法,如果想要产生包注释,需要在每一个包目录添加一个单独文件。在这里,我们有两种选择: 提供一个以package.html命名HTML文件。...这个文件必须包含一个初始以 /** */界定Javadoc注释,跟随在一个包语句之后,不包含其他代码注释。 我们还可以为所有的源文件提供一个概述性注释。...,就应该运行: javadoc -d docDirectory *.java 当然我们可以使用多种命令行方式来调整javadoc,可以使用 --author --version选项在让文档包含 @author

    99720

    Android Studio kotlin生成编辑注释代码

    更新了AS 3.1.2之后,发现新建Kotlin注释依然木有,没办法只有自己动手了。 方法很简单,编辑File Header就可以啦。 ? 只需要编辑自己想要模板就可以啦。...补充知识:Android Studio javadoc 生成注释文档 相信大家刚开始代码时候就被前辈告知了要养成注释好习惯,今天我们来了解一下如何利用我们平时注释生成文档,一起来看看吧!...既然了解了注释格式,那么我们就利用上面的注释来使用android studio生成javadoc: ? 单击进入配置页面: ?...这里主要讲以下几个地方: 首先在上面指定你需要生成文档文件夹或文件; 然后是output directorys中指定输出文档路径; 最后如果你注释是中文就需要在Othere command line...当你看到和我一样界面那么你就成功了,这里是生成了所有文档,如果没有自动打开网页,大家可以在我们指定文档输出文件夹中找到index.html打开即可,好了本文就到此为止,希望对大家有用,多多支持

    2.1K30

    Javadoc 使用详解

    很多程序对Javadoc都不重视,认识不到Javadoc作用,很多人都是这样认为:“只要写好功能就够了,Javadoc太浪费时间,也没啥作用,还不如用Javadoc时间再多些个功能呢!”...,我们知道注释是为了解释代码作用,是为了将来给自己或者别人快速了解代码,在方法内一般用行注释//比较多,是针对一小块代码做出解释,而Javadoc作用是针对整个方法或者整个做一个简要概述...假如在公司A程序员写了Javadoc,B程序员只功能不Javadoc注释,那么一般会认为A程序员会比B程序员做好。...一:简介 Javadoc用于描述或者方法作用。Javadoc可以写在上面方法上面。...@inheritDoc @inheritDoc用于注解在重写方法或者子类上,用于继承父Javadoc文档注释被继承到了子类 子类可以再加入自己注释(特殊化扩展) @return @param

    1K20

    DOC文档注释,让你代码如此清晰。

    用文档注释。然后就知道怎么弄了,以下是生成流程。 2.生成方法 先说生成方法吧,免得一开始将注释规范可能读者觉得比较繁琐,而且注释规范基本上大家都有一套自己做法。...到这里就完成了生成步骤了,下面说一下一点点注释要注意地方,对于注释规范的人可以不用看下去了,但是如果你生成api里面基本上没有什么内容,那么建议你还是看看下面的内容。...3.doc注释 3.1多行注释 对于属性,方法注释必须使用多行注释,单行注释不会生成到文档 3.2属性注释: /** 员工ID */ private String workerId; 3.3方法注释...当然,还可以加入自己定义一些注解,这些注解要生成到文档注释中就要在如上图2.3步骤声明出来,如@功能描述 3.4注释 /** * @功能描述: 接口返回错误码 * @项目版本: 1.0.0...这里可以对属性,方法,以及更多内容做模板设置,这样输入注释时候就能统一了,而且免去了多打字痛苦,上图是一个注释模板 有了这些基本上生成接口文档就够用了,当然。

    1.5K40

    细读 Thinking in Java (一)一切都是对象

    创建新数据类型: 大多数面向对象程序设计语言习惯用关键字“class”来表示“准备告诉你一种新类型对象看起来像什么样子”,Java也不例外,用class关键字来声明一个新,例如: class...参数列表 方法参数列表指定要传递给方法什么信息,在参数列表必须指定每个所传递对象类型名字。...javadoc输出是一个HTML文件,该工具使得我们只需创建和维护单一源文件,就能自动生成有用文档了。 语法 所有的javadoc命令都只能在/**注释中出现,通常一样,注释结束于*/。...所有类型注释文档都支持嵌入式HTML(、域方法)。 一些标签示例 这里将介绍一些可用于代码文档javadoc标签。 1.@see: 引用其它 @see标签允许用户引用其它文档。...,整体非常简单,重点是文档注释方面的内容,还有一些计算机基础方面部分历史方面的知识仅作了解,本系列blog是利用闲暇时间记录读书笔记,关于书中没有讲到例子这里也都给出了实例并进行了细化,旨在复习一遍

    51460

    转引注释怎么_java注释模板

    图二 自己创建是mygroup,然后点击添加live Template 添加注释方法注释。...* * @author *** * @createDate $date$ $time$ */ ​ 注释比较简单,可以参考IDEA 创建注释模板方法注释模板 – 简书 datetime都是变量...方法注释注释差别在于param字段是自己groovy脚本,如图所示,复制字符串到对应位置即可。...最近利用javadoc 工具生成注释,发现原来注解 “:” 不能有。 2. 原本方法注释返回值为空也有return,根据javadoc,无返回值不应该return。...IDEA 创建注释模板方法注释模板 – 简书 * @Description * @author: Kangxiaoan * @version * @date: $date$ */ ---- 敲黑板,

    6.9K30
    领券