广告位联系
返回顶部
分享到

Java程序中Doc文档注释介绍

java 来源:互联网 作者:秩名 发布时间:2021-10-30 08:34:35 人浏览
摘要

许多人写代码时总不喜欢写注释,每个程序员如此,嘿嘿,我也一样,不过,话说回来,该写还是要写哦!没人会喜欢一个不写注释的程序员,当然,也没有一个喜欢写注释的程序员,

许多人写代码时总不喜欢写注释,每个程序员如此,嘿嘿,我也一样,不过,话说回来,该写还是要写哦!没人会喜欢一个不写注释的程序员,当然,也没有一个喜欢写注释的程序员,今天,我们就来说说Java注释之一——Doc注释

我们知道,Java支持 3 种注释,分别是单行注释、多行注释和文档注释,我们来看看他们的样子

//单行注释
 
/*
多行注释
*/
 
/**
*@...
*....
*文档注释
*/

可能许多萌新不明白,写了这些注释有什么用呢?其实是因为初学者的代码量少,没有注释也能快速查找、修改,当代码渐渐多了起来,注释就是一个好东西了,不仅是为了自己可以清晰明了看清代码,也是为了和你一起开发项目的成员一个方便

记住,改掉不写注释这种坏习惯!!!

那么,我们今天的主题来了,什么是Doc注释呢?

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

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

这些复杂理论不必去纠结,要培养一种思想,去了解、去理解、去深入、去改变它,去懂得他,死死揪住理论是没有效果的!

我们写代码,都是有规范的,如果你写的代码可以运行,但是一团乱麻,是没人愿意使用的,因为难以维护,所以,代码不只是单纯的程序,在网络世界,我更愿意称之它为艺术品,需要你的精心镌刻

可能有人会说,不就是注释吗?这有什么的

不过,这个Doc注释可不与其他两个注释一样,注释也是存在规范的哦!

Doc注释规范

格式:

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

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

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

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

这里我要扩展一点知识,我们的Doc注释可以使用Dos命令或者IDE工具生成一个Doc文档,这个文档是HTML语言来贯穿的,所以在注释里面可以搭配一些简单的HTML代码,比如下面这几个

换行

分段

(写在段前)

放个实例样式图:

@符号的用处

我们在写Doc注释时,/** 后直接回车,会自动生成后面的注释框架,和部分@符号,那么这些@符号有什么用呢?

标签 描述 示例
@author 标识一个类的作者,一般用于类注释 @author description
@deprecated 指名一个过期的类或成员,表明该类或方法不建议使用 @deprecated description
{@docRoot} 指明当前文档根目录的路径 Directory Path
@exception 可能抛出异常的说明,一般用于方法注释 @exception exception-name explanation
{@inheritDoc} 从直接父类继承的注释 Inherits a comment from the immediate surperclass.
{@link} 插入一个到另一个主题的链接 {@link name text}
{@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 description
@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

@后面我这里部分是英文,可以写中文,比如 @author 小简

如何生成Doc文档

我们上面说过,写了Doc注释,可以生成一个Doc文档,而且是HTML格式,那么我们怎么生成呢?

第一个:Dos命令生成

javadoc [options] [packagenames] [sourcefiles]

对格式的说明:

options 表示 Javadoc 命令的选项;

packagenames 表示包名;

sourcefiles 表示源文件名;

在 cmd(命令提示符)中输入javadoc -help就可以看到 Javadoc 的用法和选项(前提是安装配置了JDK),下面列举 Javadoc 命令的常用选项:

名称 说明
-public 仅显示 public 类和成员
-protected 显示 protected/public 类和成员(默认值)
-package 显示 package/protected/public 类和成员
-private 显示所有类和成员
-d 输出文件的目标目录
-version 包含 @version 段
-author 包含 @author 段
-splitindex 将索引分为每个字母对应一个文件
-windowtitle 文档的浏览器窗口标题

用Doc生成又麻烦又慢,那还有没有其他方法呢?

第二个:IDE工具生成

我们可以用Eclipse或者IDEA生成,Eclipse我不怎么用,用IDEA给你们演示一下吧!

 在工具这个里面的JavaDoc里面,进去后是这样的

 输出目录必须选择,不然生成不了

注意了,因为Java的编码与IDEA的编码不一样,所以在其他命令形参栏目里面,要填写以下内容

1

-encoding utf8 -docencoding utf8 -charset utf8

生成之后,是这样的

 

好了,Doc注释知道用就可以,最重要的是:一定要写注释,各位程序员们,未来可期,顶峰相见


版权声明 : 本文内容来源于互联网或用户自行发布贡献,该文观点仅代表原作者本人。本站仅提供信息存储空间服务和不拥有所有权,不承担相关法律责任。如发现本站有涉嫌抄袭侵权, 违法违规的内容, 请发送邮件至2530232025#qq.cn(#换@)举报,一经查实,本站将立刻删除。
原文链接 : https://blog.csdn.net/qq_60750453/article/details/121024414
相关文章
  • SpringBoot自定义错误处理逻辑介绍

    SpringBoot自定义错误处理逻辑介绍
    1. 自定义错误页面 将自定义错误页面放在 templates 的 error 文件夹下,SpringBoot 精确匹配错误信息,使用 4xx.html 或者 5xx.html 页面可以打印错误
  • Java实现手写一个线程池的代码

    Java实现手写一个线程池的代码
    线程池技术想必大家都不陌生把,相信在平时的工作中没有少用,而且这也是面试频率非常高的一个知识点,那么大家知道它的实现原理和
  • Java实现断点续传功能的代码

    Java实现断点续传功能的代码
    题目实现:网络资源的断点续传功能。 二、解题思路 获取要下载的资源网址 显示网络资源的大小 上次读取到的字节位置以及未读取的字节
  • 你可知HashMap为什么是线程不安全的
    HashMap 的线程不安全 HashMap 的线程不安全主要体现在下面两个方面 在 jdk 1.7 中,当并发执行扩容操作时会造成环形链和数据丢失的情况 在
  • ArrayList的动态扩容机制的介绍

    ArrayList的动态扩容机制的介绍
    对于 ArrayList 的动态扩容机制想必大家都听说过,之前的文章中也谈到过,不过由于时间久远,早已忘却。 所以利用这篇文章做做笔记,加
  • JVM基础之字节码的增强技术介绍

    JVM基础之字节码的增强技术介绍
    字节码增强技术 在上文中,着重介绍了字节码的结构,这为我们了解字节码增强技术的实现打下了基础。字节码增强技术就是一类对现有字
  • Java中的字节码增强技术

    Java中的字节码增强技术
    1.字节码增强技术 字节码增强技术就是一类对现有字节码进行修改或者动态生成全新字节码文件的技术。 参考地址 2.常见技术 技术分类 类
  • Redis BloomFilter布隆过滤器原理与实现

    Redis BloomFilter布隆过滤器原理与实现
    Bloom Filter 概念 布隆过滤器(英语:Bloom Filter)是1970年由一个叫布隆的小伙子提出的。它实际上是一个很长的二进制向量和一系列随机映射
  • Java C++算法题解leetcode801使序列递增的最小交换次

    Java C++算法题解leetcode801使序列递增的最小交换次
    题目要求 思路:状态机DP 实现一:状态机 Java 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 class Solution { public int minSwap(int[] nums1, int[] nums2) { int n
  • Mybatis结果集映射与生命周期介绍

    Mybatis结果集映射与生命周期介绍
    一、ResultMap结果集映射 1、设计思想 对简单的语句做到零配置,对于复杂一点的语句,只需要描述语句之间的关系就行了 2、resultMap的应用场
  • 本站所有内容来源于互联网或用户自行发布,本站仅提供信息存储空间服务,不拥有版权,不承担法律责任。如有侵犯您的权益,请您联系站长处理!
  • Copyright © 2017-2022 F11.CN All Rights Reserved. F11站长开发者网 版权所有 | 苏ICP备2022031554号-1 | 51LA统计