许多人写代码时总不喜欢写注释，每个程序员如此，嘿嘿，我也一样

不过，话说回来，该写还是要写哦！没人会喜欢一个不写注释的程序员，当然，也没有一个喜欢写注释的程序员，今天，我们就来说说Java注释之一——Doc注释

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

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

可能许多萌新不明白，写了这些注释有什么用呢？

其实是因为初学者的代码量少，没有注释也能快速查找、修改

当代码渐渐多了起来，注释就是一个好东西了，不仅是为了自己可以清晰明了看清代码，也是为了和你一起开发项目的成员一个方便

记住，改掉不写注释这种坏习惯！！！

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

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

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

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

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

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

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

Doc注释规范

格式：

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

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

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

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

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

换行<br>

分段<p>(写在段前）

放个实例样式图：

@符号的用处

我们在写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 <directory>	输出文件的目标目录
-version	包含 @version 段
-author	包含 @author 段
-splitindex	将索引分为每个字母对应一个文件
-windowtitle <text>	文档的浏览器窗口标题

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

第二个：IDE工具生成

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

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

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

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

-encoding utf8 -docencoding utf8 -charset utf8

生成之后，是这样的

好了，Doc注释知道用就可以

最重要的是：一定要写注释，各位程序员们，未来可期，顶峰相见

Java程序中Doc（文档）注释详解相关推荐

java文档注释详解
https://blog.csdn.net/houhj168/article/details/41146415 对于Java语言,最体贴的一项设计就是它并没有打算让人们为了写程序而写程序--人们也需要 ...
java word 超链接到文档内部_Java 添加超链接到 Word 文档方法详解
在Word文档中,超链接是指在特定文本或者图片中插入的能跳转到其他位置或网页的链接,它也是我们在编辑制作Word文档时广泛使用到的功能之一.今天这篇文章就将为大家演示如何使用Free Spire.Do ...
Jsoup解析HTML实例及文档方法详解
转载自 Jsoup解析HTML实例及文档方法详解这篇文章主要介绍了Jsoup如何解析一个HTML文档.从文件加载文档.从URL加载Document等方法,对Jsoup常用方法做了详细讲解,最近提供 ...
css三种定位都脱离文档流了吗,CSS布局之脱离文档流详解——浮动、绝对定位脱离文档流的区别...
1.代码 (1)示例代码1 CSS布局之脱离文档流详解--浮动.绝对定位脱离文档流的区别 .left { width: 300px; height: 500px; background: red; f ...
Keras深度学习实战（26）——文档向量详解
Keras深度学习实战(26)--文档向量详解 0. 前言 1. 文档向量基本概念 2. 神经网络模型与数据集分析 2.1 模型分析 2.2 数据集介绍 3. 利用 Keras 构建神经网络模型生成文 ...
word的计算机功能是什么,电脑腾讯文档是什么？电脑腾讯文档功能详解
‍‍ 最近腾讯文档上线了,什么是腾讯文档呢?腾讯文档是一款可多人协作的在线文档,可同时编辑Word和Excel文档,云端实时保存.电脑腾讯文档功能受到很多用户喜爱,但是大部分用户不知道腾讯文档的具体使 ...
java开发中常用的Git命令详解
java开发中常用的Git命令详解(IDEA内如何操作) 一:写这篇文章的目的是什么? 二:使用场景在哪里? 1:当我们要使用idea去git仓库拉代码时,首先我们的idea得配置git工具 2:项目 ...
Jacob Java程序把Word文档直接转换成Html文件
2019独角兽企业重金招聘Python工程师标准>>> Jacob是Java和Windows下的Com桥,通过它我们可以在Java程序中调用COM组件.如果你的JDK是1.4,那你需 ...
java 设置pdf 编码格式_Java如何设置PDF文档背景色详解
前言一般生成的PDF文档默认的文档底色为白色,我们可以通过一定方法来更改文档的背景色,以达到文档美化以及保护双眼的作用. 以下内容提供了Java编程来设置PDF背景色的方法.包括: 设置纯色背景设 ...

Java程序中Doc（文档）注释详解

Doc注释规范

格式：

@符号的用处

如何生成Doc文档

Java程序中Doc（文档）注释详解相关推荐

最新文章

热门文章