开发这么久了,你会使用文档注释吗?Java 文档注释详解

前言


  注释是一个文件的灵魂,在我们开发中,经常会查阅各种文档,文档上都会有很详细的注释,有的甚至都有示例,那么开发这么久了,你会使用文档注释吗?下面将进行java文档注释的介绍


初始注释


  注释作用:主要是用来生成说明文件时,供使用者或者阅读者快速熟悉所设置,也是为自己以后看到能一目了然的作用。


单行注释


  • 单行注释:
  • 符号【//】
  • 格式:// 后面跟上注释内容注释内容
  • 示例如下:


//main方法
    public static void main(String[] args) {
        System.out.println("掘金 - 代码不止,掘金不停");
    }


多行注释


  • 多行注释
  • 符号【/* */】
  • 格式:/* 注释内容 */
  • 示例如下:


//main方法
    public static void main(String[] args) {
        /*
        以下执行将输出
        【掘金 - 代码不止,掘金不停】
         */
        System.out.println("掘金 - 代码不止,掘金不停");
    }


文档注释


  • 文档注释
  • 符号【/***/】
  • 格式:它以 /** 开始,以 */结束。文档注释也是说明注释,允许你在程序中嵌入关于程序的信息。你可以使用 javadoc 工具软件来生成信息,并输出到HTML文件中。
  • 示例如下:


/**
     * @MethodName: testJavaDoc
     * @Description: 测试多行文本输出
     * @param
     * @Return: void
     * @Author: JavaZhan @公众号:Java全栈架构师
     * @Date: 2020/6/13
     **/
    public static  void testJavaDoc(){
        System.out.println("掘金 - 代码不止,掘金不停");
        System.out.println("作者:小阿杰");
        System.out.println("主页地址:https://juejin.cn/user/2040300414187416/posts");
        System.out.println("欢迎关注交流学习!");
    }

  

是不是很好奇,@MethodName、@Description、@param、@Return除了文章出现的标签,还有哪些文档注释的标签呢?都是那些标签可以使用呢?下面给大家汇总了一下。


注释常用的标签


标签 描述 示例
@Author 一个类或者方法的的作者 @author description
@Deprecated 一个过期的类或成员 @deprecated description
@Date 创建日期 @Date: 2020/6/13
{@docRoot} 当前文档根目录的路径 Directory Path
@exception 抛出的异常 @exception exception-name explanation
{@inheritDoc} 从直接父类继承的注释 Inherits a comment from the immediate surperclass.
{@link} 插入一个到另一个主题的链接 {@link name javadoc}
{@linkplain} 插入一个到另一个主题的链接,但是该链接显示纯文本字体 Inserts an in-line link to another topic.
@param 方法的参数 @param parameter-name explanation
@return 返回值类型 @return explanation
@see 指定一个到另一个主题的链接 @see anchor
@serial 一个序列化属性 @serial description
@serialData 说明通过writeObject( ) 和 writeExternal( )方法写的数据 @serialData
@serialField 说明一个ObjectStreamField组件 @serialField name type description
@since 标记当引入一个特定的变化时 @since release
@throws 和 @exception标签一样,抛出异常 The @throws tag has the same meaning as the @exception tag.
{@value} 显示常量的值,该常量必须是static属性。 Displays the value of a constant, which must be a static field.
@version 指定类的版本 @version info
@MethodName 方法名称 @MethodName testJavaDoc

  在/** 之后,第一行或几行是关于类、变量和方法的主要描述。注释文档可以根据标签为类、方法、接口、枚举等提供便于开发人员和使用人员易阅读的文本内容。


快速开始


生成文档


  本次生成文档采用javadoc生成。javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档了。

  javadoc命令是用来生成自己API文档的,使用方式:使用命令行在目标文件所在目录输入javadoc +文件名.java。 命令如下:


javadoc ****.java


进入目录


  如下图,进入将要执行生成的文件,输入:javadoc ****.java

开发这么久了,你会使用文档注释吗?Java 文档注释详解

执行javadoc Tests.java,生成如下文件和文件夹。开发这么久了,你会使用文档注释吗?Java 文档注释详解

  点击其中index.html,已经进入到文档页面。


开发这么久了,你会使用文档注释吗?Java 文档注释详解



结语


  以上就是Java 文档注释生成的过程。

上一篇:使用Markdown写博客的一些模板


下一篇:Linux时间子系统之一:clock source(时钟源)【转】