Javadoc标签和Javadoc注释规范说明

最近看源码，一些Javadoc常见的注释整理下

Javadoc是Sun公司提供的一个技术，从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。

Javadoc命令是用来生成自己的API文档，使用方式：

javadoc 源文件名.java

javadoc -d 文档存放目录 源文件名.java

通过IDEA生成Javadoc ： Tools -> Generate JavaDoc

javadoc标签

标签 说明
@author 作者标识
@version 版本号
@return 对函数返回值的描述
@deprecated 标识过期API（为了保证兼容性，仍可用，但不推荐用）
@throws 构造函数或方法会抛出的异常
@exception 同@throws
@see 引用，查看相关的内容，如类，方法，变量等，必须顶头写
{@link 包.类#成员} 引用，同@see，但可写在任意位置
{@value} 对常量注释，如果其值包含在文档中，通过改标签引用常量的值
{@code}} {@code text}将文本标记为code，会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名，都需要使用@code进行标记
@param 说明方法的参数
@inheritDoc 用于继承父类中的Javadoc，父类的文档注释，被继承到了子类

javadoc注释规范

一、 Java文档

// 注释一行
/ *  */ 注释若干行
/**  ……*/ 注释若干行，写入Javadoc文档

二、文档格式

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

第一段：概要描述，通常用一句话或者一段话简要描述该类的作用，以英文句号结束

第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束

第三段：文档标注，用于标注作者，创建时间，参阅类等信息

生成文档是HTML格式。
换行<br>
分段<p>(写在段前）)

示例

/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示，false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
  frame.show(b);
  }

补充：Java的三种注释 Javadoc标记*

三种注释方法：

1、单行注释 //注释的内容

2、多行注释 /*......*/

3、/**......*/，这种方式和第二种方式相似。这种格式是为了便于javadoc程序自动生成文档。

下面介绍一下Javadoc的标记：


JavaDoc 标 记
解释

@version
指定版本信息

@since
指定最早出现在哪个版本

@author
指定作者

@see
生成参考其他的JavaDoc文档的连接

@link
生成参考其他的JavaDoc文档，它和@see标记的区别在于，@link标记能够嵌入到注释语句中，为注释语句中的特殊词汇生成连接。 eg.{@link Hello}

@deprecated
用来注明被注释的类、变量或方法已经不提倡使用，在将来的版本中有可能被废弃

@param
描述方法的参数

@return
描述方法的返回值

@throws
描述方法抛出的异常，指明抛出异常的条件

特别声明：

（1）javadoc针对public类生成注释文档

（2）javadoc只能在public、protected修饰的方法或者属性之上

（3）javadoc注释的格式化：前导*号和HTML标签

（4）javadoc注释要仅靠在类、属性、方法之前

下面主要举例说明第三种注释的应用：

（1）首先编写.java文件

（2）在命令行中执行以下dos命令：

javadoc *.java //根据相应的Java源代码及其说明语句生成HTML文档

//javadoc标记：是@开头的，对javadoc而言，特殊的标记。

（3）在当前目录下就会产生doc文件夹，里面有一系列的.html文件

附上代码：

<span style="font-size:18px;">*/
/**javadoc注释的内容
*/
public class Hello{
  /**属性上的注释*/
  public String name;
  /**这是main方法,是程序的入口
  *@param args 用户输入参数
  */
  public static void main(String[] args){
 System.out.println("Hello World!");
    f1();
  }
  /** 这是第1个方法,其作用是...*/
  public static void f1(){
   System.out.println("f1()！");
  }
}</span>
<span style="font-size:18px;">import java.io.IOException;
/**javadoc注释内容
*@since 1.0
*@version 1.1
*@author Blue Jey
*<br>链接到另一个文档{@link Hello},就这些
*see Hello
*/
public class HelloWorld{
 /**非public，protected 属性上的注释不生成*/
 public String name;
 /**这是main方法，是程序的入口
 *@param args 用户输入的参数，是数组
 *@throws IOException main方法io异常
 */
 public static void main(String args[]) throws IOException{
 System.out.println("hello World!");

 f1();
 f2(1);
 }
 /**这是第一个方法，其作用是....
 *@deprecated 从版本1.2开始，不再建议使用此方法
 */
 public static void f1(){
 System.out.println("fl()!");
 }
 /**这是第二个方法，其作用是....
 *@return 返回是否OK
 *@param i 输入参数i
 *@see Hello
 *@throws IOException io异常
 */
 public static String f2(int i)throws IOException{
 System.out.println("f1()!");
 return "OK";
 }
 } </span>

注意：

如果源文件中有用到@version,@author标记，则在执行javadoc命令时，要加-version -author

javadoc -version -author -d doc *.java

（其中用-version用于提取源文件中的版本信息 -author用于提取源文件中的作者信息）

以上为个人经验，希望能给大家一个参考，也希望大家多多支持我们。如有错误或未考虑完全的地方，望不吝赐教。

赞 (0)

相关推荐

  • Maven打包jar生成javadoc文件和source文件代码实例

    这篇文章主要介绍了Maven打包jar生成javadoc文件和source文件代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 官方文章 : https://maven.apache.org/plugin-developers/cookbook/attach-source-javadoc-artifacts.html 生成文件的样本 attach-source-javadoc |-- pom.xml |-- src\ `-- target

  • 在IntelliJ IDEA中为自己设计的类库生成JavaDoc的方法示例

    因为某个项目需要,为团队其他兄弟姐妹开发了一个 XML 分析处理器,并将其设计为一个类库,提供相应的 API 接口.为了方便大家的使用,需要生成对应的 JavaDoc 帮助文档,就像 JavaSE 标准库提供的 JavaDoc 那样.我的开发工具为 IntelliJ IDEA 12.1.6,本身提供了很好的 JavaDoc 生成功能,以及标准 JavaDoc 注释转换功能,其实质是在代码编写过程中,按照标准 JavaDoc 的注释要求,为需要暴露给使用者的类.方法以及其他成员编写注释.然后使用

  • Javadoc 具体使用详解

    很多程序对Javadoc都不重视,认识不到Javadoc的作用,很多人都是这样认为的:"我只要写好功能就够了,写Javadoc太浪费时间,也没啥作用,还不如用写Javadoc的时间再多些个功能呢!",我们知道注释是为了解释代码的作用的,是为了将来给自己或者别人快速了解代码的,在方法内一般用行注释//的比较多,是针对一小块代码做出解释的,而Javadoc的作用是针对整个方法或者整个类做一个简要的概述的,使得别人不通过看具体方法代码就能知道某个方法或者某个类的作用和功能.写了Javadoc

  • 解决阿里代码规范检测中方法缺少javadoc注释的问题

    一.问题描述 安装了阿里代码检测的插件后,敲一个简单的方法,发现提示有问题,如下 /** * 查找User的集合 */ List<User> findAll(); 提示信息为: 方法[findAll]缺少javadoc注释 进一步查看完整文档里面关于方法注释的规范为 所有的抽象方法(包括接口中的方法)必须要用javadoc注释.除了返回值.参数.异常说明外,还必须指出该方法做什么事情,实现什么功能. 说明:如有实现和调用注意事项,请一并说明. /** * fetch data by rule

  • 浅谈Android Studio导出javadoc文档操作及问题的解决

    1.在Android studio中进行打开一个项目的文件之后,然后进行点击Android stuio中菜单中的"tools"的选项.在弹出了下拉菜单中,进行选中下拉菜单中的"Generate JavaDoc"的选项. 2.在弹出界面中 Output directory是你即将生产的javadoc文件的存储位置,图中1指示的位置:正常点击ok即可: 但是如果有异常情况 比如空指针异常或者文档乱码 java.lang.NullPointerException 或者 j

  • Javadoc标签和Javadoc注释规范说明

    最近看源码,一些Javadoc常见的注释整理下 Javadoc是Sun公司提供的一个技术,从程序源代码中抽取类.方法.成员等注释形成一个和源代码配套的API帮助文档. Javadoc命令是用来生成自己的API文档,使用方式: javadoc 源文件名.java javadoc -d 文档存放目录 源文件名.java 通过IDEA生成Javadoc : Tools -> Generate JavaDoc javadoc标签 标签 说明 @author 作者标识 @version 版本号 @retu

  • Java代码注释规范详解

    Java代码注释规范详解

    代码附有注释对程序开发者来说非常重要,随着技术的发展,在项目开发过程中,必须要求程序员写好代码注释,这样有利于代码后续的编写和使用. 基本的要求: 1.注释形式统一 在整个应用程序中,使用具有一致的标点和结构的样式来构造注释.如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范. 2.注释内容准确简洁 内容要简单.明了.含义准确,防止注释的多义性,错误的注释不但无益反而有害. 3.基本注释(必须加) (a) 类(接口)的注释 (b) 构造函

  • Java代码注释规范(动力节点整理)

    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在日常开发中使用的代码注释规范,供大家参考下. 1. 注释形式统一 在整个应用程序中,使用具有一致的标点和结构的样式来构造注释.如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范. 2. 注释内容准确简洁 内容要简单.明了.含义准确,防止注释的多义性,错误的注释不但无益反而有害

  • PDP Document 代码注释规范第1/2页

    1. 什么是phpDocumentor ? PHPDocumentor是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档.老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便. PHPDocumentor工作时,会扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释,

  • PHP Document 代码注释规范

    1. 什么是phpDocumentor ? PHPDocumentor 是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档.老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便. PHPDocumentor工作时,会扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释

  • 关于PHPDocument 代码注释规范的总结

    1. 安装phpDocumentor(不推荐命令行安装)在http://manual.phpdoc.org/下载最新版本的PhpDoc放在web服务器目录下使得通过浏览器可以访问到点击files按钮,选择要处理的php文件或文件夹还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理.然后点击output按钮来选择生成文档的存放路径和格式.最后点击create,phpdocumentor就会自动开始生成文档了. 2．如何写PHP规范注释所有的文档标记都是在每一行的 * 后

  • Python类和方法注释规范说明

    Python类和方法注释规范说明

    目录 Python类和方法注释规范 注释风格 小技巧 代码规范(含代码注释) 代码缩进和冒号 空行分隔代码段 包.模块的命名规范 类和对象的命名规范 函数的命名规范 代码注释 Python类和方法注释规范 注释风格 reStructuredText(PyCharm默认) def func(path, field_storage, temporary): '''基本描述 详细描述 :param path: The path of the file to wrap :type path: str :

  • php 注释规范

    @access 使用范围:class,function,var,define,module 该标记用于指明关键字的存取权限:private.public或proteced @author 指明作者 @copyright 使用范围:class,function,var,define,module,use 指明版权信息 @deprecated 使用范围:class,function,var,define,module,constent,global,include 指明不用或者废弃的关键字 @exa

  • Python代码注释规范代码实例解析

    一.代码注释介绍 注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码. 注释是编写程序时,写程序的人给一个语句.程序段.函数等的解释或提示,能提高程序代码的可读性. 在有处理逻辑的代码中,源程序有效注释量必须在20%以上. 二.代码注释分类 行注释:在符号后那一行不会被编译(显示) 块注释:被块注释符号中间的部分不会被编译 三.python代码注释基础 Python中使用#表示单行注释.单行注释可以作为单独的一行放在被注释代码行之上,也可以放在语句或表达式之后.如下例子: name

  • Java编程之jdk1.4,jdk1.5和jdk1.6的区别分析(经典)

    本文结合实例详细分析了Java编程之jdk1.4,jdk1.5和jdk1.6的区别.分享给大家供大家参考,具体如下: 简单说:1.4和1.5最大的区别有两个,一个是1.5有泛型,另一个1.5可以自动封装八大基本数据类型的封装数据类型,即,Integer a = 4这个1.4是不可以的.1.5和1.6的区别不大.1.6我觉得最多的变化,我觉得最大的部分是在GUI上面,提供了很多方便的布局管理和扩展. 这段时间进了一家电子政务公司,都用weblogic8,那咱就用jdk1.4吧,eclipse一改j

随机推荐