Java程序中Doc文档注释示例教程

2024-11-01 10:24:17

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程序Doc文档注释的资料请关注我们其它相关文章！

Javadoc标签和Javadoc注释规范说明

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

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

在Java中,注解(Annotation)引入始于Java5,用来描述Java代码的元信息,通常情况下注解不会直接影响代码的执行,尽管有些注解可以用来做到影响代码执行. 注解可以做什么 Java中的注解通常扮演以下角色编译器指令构建时指令运行时指令其中 Java内置了三种编译器指令,本文后面部分会重点介绍 Java注解可以应用在构建时,即当你构建你的项目时.构建过程包括生成源码,编译源码,生成xml文件,打包编译的源码和文件到JAR包等.软件的构建通常使用诸如Apache Ant和Mav
Java文档注释用法+JavaDoc的使用说明

简介文档注释负责描述类.接口.方法.构造器.成员属性.可以被JDK提供的工具 javadoc 所解析,自动生成一套以网页文件形式体现该程序说明文档的注释. 注意:文档注释必须写在类.接口.方法.构造器.成员字段前面,写在其他位置无效. JavaDoc 官方说明 How to Write Doc Comments for the Javadoc Tool 写在类上面的JavaDoc 写在类上的文档标注一般分为三段: 第一段:概要描述,通常用一句或者一段话简要描述该类的作用,以英文句号作为结束第
全面解析Java中的注解与注释

注解一.什么是 Annotation? (注解 or 注释) Annotation, 准确的翻译应该是 -- 注解. 和注释的作用完全不一样. Annotation 是JDK5.0及以后版本引入的一个特性. 与类.接口.枚举是在同一个层次,可以成为java 的一个类型. 语法是以@ 开头简单来说, 注释是程序员对源代码的类,方法,属性等做的一些记忆或提示性描述(比如这个方法是做什么用的),是给人来看的. 注解则是Java 编译器可以理解的部分,是给编译器看的. 举个简单的例子来看一下注解的使
Java程序中Doc文档注释示例教程

目录 Doc注释规范 @符号的用处如何生成Doc文档第一个:Dos命令生成第二个:IDE工具生成许多人写代码时总不喜欢写注释,每个程序员如此,嘿嘿,我也一样不过,话说回来,该写还是要写哦!没人会喜欢一个不写注释的程序员,当然,也没有一个喜欢写注释的程序员,今天,我们就来说说Java注释之一--Doc注释我们知道,Java支持 3 种注释,分别是单行注释.多行注释和文档注释,我们来看看他们的样子 //单行注释 /* 多行注释 */ /** *@... *.... *文档注释 *
Java实现合并word文档的示例代码

目录说明实现 1.首先定义好主文档 2.定义需要追加的文档 3. 代码实现 4. 成果展示说明在做项目中,遇到了一种情况,需要将一个小word文档的内容插入到一个大word(主文档)中. 实现 1.首先定义好主文档在主文档需要插入小word文档的位置上添加一个书签,这个书签名字要记住,后面要用. 2.定义需要追加的文档 3. 代码实现 package com.test.word; import com.aspose.words.Body; import com.aspose.words
java程序中protobuf的基本用法示例

目录简介为什么使用protobuf 定义.proto文件编译协议文件详解生成的文件 Builders 和 Messages 序列化和反序列化协议扩展总结简介 Protocol Buffer是google出品的一种对象序列化的方式,它的体积小传输快,深得大家的喜爱.protobuf是一种平台无关和语言无关的协议,通过protobuf的定义文件,可以轻松的将其转换成多种语言的实现,非常方便. 今天将会给大家介绍一下,protobuf的基本使用和同java结合的具体案例. 为什么使用pr
c#中xml文档注释编译dll引用到其它项目示例

复制代码代码如下: <#@ template debug="True" hostspecific="True" language="C#" #><#@ assembly name="System.Core" #><#@ assembly name="System.Data" #><#@ assembly name="System.xml" #&
Java的文档注释之生成帮助文档的实例

示例: /** * Title: Person类<br/> * Description:通过Person类说明Java中的文档注释<br/> * Company: *** * @author *** * @version 1.0 */ public class Person { /** * 这个是Person类的构造方法 * @param name Person 的名字 * */ public Person(String name) { //执行语句: } /** * 这是read
IntelliJ IDEA2022中的Java文档注释设置、操作方法

1.打开IDEA,点击setting-Editor-Live Templates. 2.点击右方的“+”准备进行文档注释的内容和快捷键设置. 右键,选中 change context,勾选中Java. 3.自定义文档注释模板,在Abbreviation中输入模块名称,在Description中输入描述,在Template text中输入注释内容. 自定义的注释内容依次是描述.作者.日期.参数. /** *@description: *@author:$USER$ *@date:$DATE$ $T
Java开发SpringBoot集成接口文档实现示例

目录 swagger vs smart-doc Swagger的代码侵入性比较强原生swagger不支持接口的参数分组简单罗列一下smart-doc的优点 SpringBoot集成 smart-doc 引入依赖,版本选择最新版本新建配置文件smart-doc.json 通过执行maven 命令生成对应的接口文档访问接口文档功能增强 1. 开启调试 2. 通用响应体 3. 自定义Header 4. 参数分组 5. idea配置doc 6. 完整配置小结之前我在SpringBoot老鸟
Java实现PDF转为Word文档的示例代码

目录代码编译环境将 PDF 转换为固定布局的 Doc/Docx 文档完整代码将 PDF 转换为流动形态的 Doc/Docx 文档完整代码效果图众所周知,PDF文档除了具有较强稳定性和兼容性外, 还具有较强的安全性,在工作中可以有效避免别人无意中对文档内容进行修改.但与此同时,也妨碍了对文档的正常的修改.这时我们可以将PDF转为Word文档进行修改或再编辑.使用软件将 PDF 文档转换为 Word 文档十分简单,然而要在转换时保持布局甚至字体格式却并不容易.本文将分为以下两部分介绍如
Java解析word,获取文档中图片位置的方法

前言(背景介绍): Apache POI是Apache基金会下一个开源的项目,用来处理office系列的文档,能够创建和解析word.excel.ppt格式的文档. 其中对word文档的处理有两个技术,分别是HWPF(.doc)和XWPF(.docx).如果你对这两个技术熟悉的话,就应该能明白使用java解析word文档的痛楚所在. 其中两个最大的问题在于: 第一是这两个类并没有统一的父类和接口(隔壁的XSSF和HSSF投过来鄙视的眼光),所以没法进行同一格式的接口式编程: 第二是官方API中并