【JAVA】javadoc,如何生成标准的JAVA API文档

 

4cdbd0f2fe404d5fb6849eb73a7ce9a0.png

目录

1.什么是JAVA DOC

2.标签

3.命令


 

1.什么是JAVA DOC

当我们写完JAVA代码,别人要调用我们的代码的时候要是没有API文档是很痛苦的,只能跟进源码去一个个的看,一个个方法的猜,并且JAVA本来就不是一个重复造轮子的游戏,一般一些常用的轮子早就已经早好了,直接拿来用就是。但是拿来用的时候往往由于API文档的缺失或者不规范,造成使用上的很多痛苦,大家在很多实际工作中经常也会遇到类似的场景:

公司多年累积下来的工具类或者提供底层能力的公共模块里面积累了很多能力,公司为了代码规范也要求我们尽量去调用这些工具类或者公共模块。但是:

  • 没有API文档或者文档写的很烂

  • 参数列表动不动就很长,数十个甚至几十个参数

  • 参数列表没有注释,出现一些莫名其妙的参数,都不知道怎么传

  • 方法名也不能见名知意

  • 造成往往要用这些公共能力的时候甚至还要去读源码

有读源码这个时间,可能自己都重新写了一个了,而且自己写的,可能比祖传下来的那些工具类还更“清爽”一些。于是系统内越来越多工具类堆积,重复造的轮子越来越多,“屎山”越堆越高。

即使有时候我们有API文档,但是各类API文档,格式,内容都不相同,没有统一的规范,读起来其实也很慢。所以有没有一个统一的规范喃?JAVA官方其实早就想到了这个问题,在JDK1.1发布的时候就附带了JAVA DOC,支持用标签注释的方式给各个方法做好规范的说明,然后用JAVA命令一键生成可视化的HTML页面作为API。

2.标签

标签是JAVA DOC的核心,用什么标签,JAVA DOC最后就会对应生成哪些API文档内容:

@author:

   /*** @author John Doe*/public class MyClass {}

@version:

   /*** @version 1.0.1*/public class MyClass {}

@param:

   /*** Concatenates two strings.* @param string1 The first string to concatenate.* @param string2 The second string to concatenate.* @return The concatenated string.*/public String concatenateStrings(String string1, String string2) {return string1 + string2;}

@return:

   /*** Returns the sum of two integers.* @param num1 The first integer.* @param num2 The second integer.* @return The sum of num1 and num2.*/public int add(int num1, int num2) {return num1 + num2;}

@throws 或 @exception: 描述方法可能抛出的异常。

   /*** Divides two numbers and throws an exception if the divisor is zero.* @param dividend The number to be divided.* @param divisor The divisor.* @return The result of the division.* @throws ArithmeticException If the divisor is zero.*/public double safeDivide(double dividend, double divisor) {if (divisor == 0) {throw new ArithmeticException("Divisor cannot be zero.");}return dividend / divisor;}

@see:

   /*** See {@link java.util.ArrayList} for more information on dynamic arrays.*/public class MyDynamicArray {}

@link: 创建一个链接到其他类、方法或字段的链接。

   /*** This method uses the {@link java.util.Collections#shuffle(List)} method to randomize the list.*/public void shuffleList(List<?> list) {Collections.shuffle(list);}

@since: 指定该元素是从哪个版本开始引入的。

   /*** A utility class for working with dates.* @since 1.5*/public class DateUtils {}

@deprecated: 标记不再推荐使用的元素。

   /*** Old method that should not be used anymore.* @deprecated Use the {@link #newMethod()} instead.*/@Deprecatedpublic void oldMethod() {}

@inheritDoc: 继承父类或接口的 JavaDoc。

    /*** {@inheritDoc}*/@Overridepublic void someMethod() {// Implementation}

@parametricType: 用于描述泛型类型参数。

    /*** Represents a generic collection.* @param <E> The type of elements in this collection.*/public class MyCollection<E> {}

@serialField 和 @serialData: 用于序列化类的字段和数据。

/*** A serializable class.* @serialField name The name of the object.* @serialData The length of the name.*/
@Serial
private static final long serialVersionUID = 1L;
​
private String name;
// serialization logic

3.命令

javadoc命令用于生成API文档,其支持多种参数:

javadoc [options] [source files]

常用参数:

  • -d <directory>: 指定输出目录,存放生成的 HTML 文件。
  • -sourcepath <pathlist>: 指定源文件路径,可以是多个路径,用分隔符(如冒号或分号)分隔。
  • -subpackages <packagename>: 递归处理指定包及其子包下的所有类。
  • -classpath <classpath>: 设置类路径,用于解析类型引用。
  • -encoding <encoding>: 指定源文件的字符编码。
  • -charset <charset>: 指定生成文档时使用的字符集。
  • -windowtitle <text>: 设置文档窗口标题。
  • -doctitle <text>: 设置文档页面的标题。
  • -overview <filename>: 指定概述文件,用于文档的首页内容。
  • -exclude <patternlist>: 指定要排除的包或类的模式列表。
  • -private: 包含私有成员的文档。
  • -protected: 默认行为,包含受保护和公开成员的文档。
  • -public: 只包含公共成员的文档。

示例:

假设你有一个名为 com.example 的包,位于 /src/main/java 目录下,你想生成包含所有公共和受保护成员的 API 文档,并将输出文件保存在 /docs/api 目录下,同时指定字符编码为 UTF-8,可以使用以下命令:

javadoc -encoding UTF-8 -charset UTF-8 -d /docs/api -sourcepath /src/main/java -subpackages com.example

搞一个类来把注解都用上,然后生成API文档看看:

package com.eryi.config;import java.io.File;
import java.io.FileWriter;
import java.io.IOException;/*** @author John Doe* @version 1.0.0* @since 2022-04-01* @deprecated Since version 1.1.0, use the {@link BetterFileManager} instead.* This class provides basic file management operations.*/
@Deprecated
public class FileManager {/*** @param filePath The path of the file to check.* @return True if the file exists, false otherwise.* @see File#exists()* @throws NullPointerException If the filePath is null.*/public boolean fileExists(String filePath) {if (filePath == null) {throw new NullPointerException("FilePath cannot be null.");}File file = new File(filePath);return file.exists();}/*** @param fileName The name of the file to create.* @param content The content to write into the file.* @return The newly created file.* @throws IOException If there's any issue creating or writing to the file.* @see File#createNewFile()* @see FileWriter*/public File createFileWithContent(String fileName, String content) throws IOException {File file = new File(fileName);if (!file.createNewFile()) {throw new IOException("Failed to create file: " + fileName);}try (FileWriter writer = new FileWriter(file)) {writer.write(content);}return file;}/*** A sample file path constant.* @since 1.0.0*/@Deprecatedpublic static final String SAMPLE_FILE_PATH = "resources/sample.txt";/*** @param args Command-line arguments (not used in this example).*/public static void main(String[] args) {FileManager fileManager = new FileManager();System.out.println("Does sample file exist? " + fileManager.fileExists(SAMPLE_FILE_PATH));}
}

直接JAVADOC:

82f2e61264ab41cc86c3ba0659c1b986.png

会在路径下生成一堆东西,需要用的只有index.html,其它的都是为了支持这个index.html的资源文件而已:

650a6514057f443aa5ac4b82f70712e2.png

看看效果:

可以看到关于这个类的什么都有:

9243bbcd81ba43059d3c39bc5d0b9da7.png

732db52ce1dd4011b79a275f141938a0.png

 

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/diannao/24834.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

探索LLM 在金融领域有哪些潜在应用——通过使用 GPT-4 测试金融工程、市场预测和风险管理等 11 项任务

概述 近年来&#xff0c;用于自然语言理解和生成的人工智能技术在自然语言处理领域取得了突破性进展&#xff0c;OpenAI 的 GPT 和其他大规模语言模型在该领域取得了显著进步。这些模型通过先进的计算能力和算法&#xff0c;展示了处理复杂任务的能力&#xff0c;如理解复杂语…

vue2组件封装实战系列之tag组件

作为本系列的第一篇文章&#xff0c;不会过于的繁杂&#xff0c;并且前期的组件都会是比较简单的基础组件&#xff01;但是不要忽视这些基础组件&#xff0c;因为纵观elementui、elementplus还是其他的流行组件库&#xff0c;组件库的封装都是套娃式的&#xff0c;很多复杂组件…

关于python中的关键字参数

在python语言中存在两种传参方式&#xff1a; 第一种是按照先后顺序来传参&#xff0c;这种传参风格&#xff0c;称为“位置参数”这是各个编程语言中最普遍的方式。 关键字传参~按照形参的名字来进行传参&#xff01; 如上图所示&#xff0c;在函数中使用关键字传参的最大作…

【Java数据结构】—— 一维数组

一维数组 在计算机语言中数组是非常重要的集合类型&#xff0c;大部分计算机语言中数组具有如下三个基本特性&#xff1a; 一致性&#xff1a;数组只能保存相同数据类型元素&#xff0c;元素的数据类型可以是任何相同的数据类型。有序性&#xff1a;数组中的元素是有序的&…

Python中的函数式编程概念

Python中的函数式编程&#xff08;Functional Programming&#xff09;是一种编程范式&#xff0c;它强调使用函数作为主要的编程构建块&#xff0c;并且避免改变状态&#xff08;即避免使用可变的数据结构和变量&#xff09;和可变数据。虽然Python本身是一种多范式编程语言&a…

计算机网络 ——网络层(IPv4地址)

计算机网络 ——网络层&#xff08;IPv4地址&#xff09; 什么是IPv4地址IP地址的分类特殊的IP地址 查看自己的IPv4地址 我们今天来看IPv4地址&#xff1a; 什么是IPv4地址 IPv4&#xff08;Internet Protocol version 4&#xff09;是第四版互联网协议&#xff0c;是第一个被…

使用CodeGen进行程序综合推理

Program Synthesis with CodeGen — ROCm Blogs (amd.com) CodeGen是基于标准Transformer的自回归语言模型家族&#xff0c;用于程序合成&#xff0c;正如作者所定义的&#xff0c;它是一种利用输入-输出示例或自然语言描述生成解决指定问题的计算机程序的方法。 我们将测试的…

mqtt-emqx:paho.mqttv5的简单例子

# 安装emqx 请参考【https://blog.csdn.net/chenhz2284/article/details/139551293?spm1001.2014.3001.5502】 # 下面是示例代码 【pom.xml】 <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</…

[office] excel做曲线图的方法步骤详解 #经验分享#知识分享#其他

excel做曲线图的方法步骤详解 Excel是当今社会最流行用的办公软件之一&#xff0c;Excel可以用于数据的整理、分析、对比。可以更直观的看到数据的变化情况&#xff0c;而有很多时候需要制作曲线图表进行数据比较&#xff0c;因此&#xff0c;下面是小编整理的如何用excel做曲线…

spark-3.5.1+Hadoop 3.4.0+Hive4.0 分布式集群 安装配置

Hadoop安装参考: Hadoop 3.4.0HBase2.5.8ZooKeeper3.8.4Hive4.0Sqoop 分布式高可用集群部署安装 大数据系列二-CSDN博客 一 下载:Downloads | Apache Spark 1 下载Maven – Welcome to Apache Maven # maven安装及配置教程 wget https://dlcdn.apache.org/maven/maven-3/3.8…

二叉树的右视图-力扣

这道题目是二叉树的层序遍历的扩展&#xff0c;对二叉树进行层序遍历&#xff0c;判断节点是否为该层的最后一个节点&#xff0c;如果是&#xff0c;则将其的数值添加到返回数组中。 /*** Definition for a binary tree node.* struct TreeNode {* int val;* TreeNode…

mqtt-emqx:简单安装emqx

安装依赖 yum install -y epel-release libatomic下载 cd /chz/install/emqx wget https://www.emqx.com/en/downloads/broker/5.7.0/emqx-5.7.0-el7-amd64.tar.gz解压 mkdir -p emqx && tar -zxvf emqx-5.7.0-el7-amd64.tar.gz -C emqx后台运行 cd /chz/install/e…

10、有条件提前退出关键字Return From Keyword If【robot framework】

在 Robot Framework 中&#xff0c;Return From Keyword If 是一个有用的关键字&#xff0c;它允许你在特定条件下从关键字中返回。这在需要在满足某个条件时提前退出关键字的情况下特别有用。 以下是 Return From Keyword If 的语法和使用示例&#xff1a; 语法 Return From…

分布式事务Seata中XA和AT模式介绍

Seata中XA和AT模式介绍 分布式事务介绍分布式解决方案解决分布式事务的思路Seata的架构Seata中的XA模式Seata的XA模型流程XA模式优缺点实现XA模式 Seata中的AT模式Seata中的AT模式流程实现AT模式AT模式优缺点 AT模式与XA模式的区别 分布式事务介绍 分布式事务&#xff0c;就是…

Hbase中Rowkey的设计方法

Hbase中Rowkey的设计方法 过去对于Rowkey设计方法缺乏理解&#xff0c;最近结合多篇博主的文章&#xff0c;进行了学习。有不少心得体会。总结下来供后续学习和回顾。 ##一、设计Rowkey的三个原则 1.长度原则&#xff1a;长度不能太长&#xff0c;小于100个字节。可以偏端一…

TypeScript是前端语言吗:一场深入而复杂的探讨

TypeScript是前端语言吗&#xff1a;一场深入而复杂的探讨 在编程的世界里&#xff0c;TypeScript是否属于前端语言&#xff0c;似乎是一个简单而又复杂的问题。它似乎简单得可以直接回答“是”或“否”&#xff0c;然而&#xff0c;深入其背后&#xff0c;我们却会发现这个问…

代码随想录算法训练营第36期DAY50

DAY50 如果写累了就去写套磁信吧。 198打家劫舍 class Solution {public: int rob(vector<int>& nums) { vector<int> dp(nums.size()); dp[0]nums[0]; if(nums.size()1) return nums[0]; dp[1]max(nums[0],nums[1]); …

【中颖】SH79F9202 串口通信

头文件 uart.h #ifndef UART_H #define UART_H#include "SH79F9202.h" #include "LCD.h" #include "timer2.h" #include "timer5.h" #include "cpu.h" #include "key.h" #include "io.h" #include &qu…

Meta Llama 3 RMSNorm(Root Mean Square Layer Normalization)

Meta Llama 3 RMSNorm&#xff08;Root Mean Square Layer Normalization&#xff09; flyfish 目录 Meta Llama 3 RMSNorm&#xff08;Root Mean Square Layer Normalization&#xff09;先看LayerNorm和BatchNorm举个例子计算 LayerNormRMSNorm 的整个计算过程实际代码实现结…

OpenCV的核心数据结构

Mat类 Mat类是OpenCV中最重要的数据结构之一&#xff0c;用于表示图像和矩阵数据。Mat类封装了多维数组&#xff0c;并提供了多种操作图像数据的方法和函数。 Mat类的主要属性和方法 构造函数&#xff1a; Mat()&#xff1a;创建一个空的Mat对象。Mat(int rows, int cols, int…