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

news2024/11/10 16:34:32

 

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.
    */
   @Deprecated
   public void oldMethod() {
   }

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

    /**
     * {@inheritDoc}
     */
    @Override
    public 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
     */
    @Deprecated
    public 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.coloradmin.cn/o/1715423.html

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

相关文章

单链表经典算法题理解

目录 1. 前言&#xff1a; 2. 移除链表元素 3. 反转链表 4. 合并两个有序链表 5. 链表的中间节点 6. 环形链表的约瑟夫问题 7. 分割链表 1. 前言&#xff1a; 当我们学习了单链表之后&#xff0c;我能可以尝试的刷一下题了&#xff0c;以下分享一下几道题的解法 2. 移…

ElementUI之el-table标题列中显示el-tooltip

ElementUI之el-table标题列中显示el-tooltip 文章目录 ElementUI之el-table标题列中显示el-tooltip1. el-table标题列中显示el-tooltip2. 实现代码3. 展示效果 1. el-table标题列中显示el-tooltip 在el-table-column标签内添加具名插槽v-slot:header 在el-tooltip标签中使用具…

《TCP/IP网络编程》(第十二章)I/O复用(2)

下面是基于I/O复用的回声服务器端和客户端代码 Linux系统 服务器端代码 #include <stdio.h> #include <stdlib.h> #include <string.h> #include <unistd.h> // POSIX标准定义的通用函数&#xff0c;如close() #include <arpa/inet.h> // 提…

JVM(四)

在上一篇中&#xff0c;介绍了JVM组件中的运行时数据区域&#xff0c;这一篇主要介绍垃圾回收器 JVM架构图&#xff1a; 1、垃圾回收概述 在第一篇中介绍JVM特点时&#xff0c;有提到过内存管理&#xff0c;即Java语言相对于C&#xff0c;C进行的优化&#xff0c;可以在适当的…

DiskCatalogMaker for Mac:您的磁盘目录管理专家

对于需要管理大量磁盘文件的用户来说&#xff0c;DiskCatalogMaker for Mac无疑是一款不可或缺的工具。这款专为Mac用户设计的磁盘目录制作软件&#xff0c;以其简洁的操作界面和强大的功能&#xff0c;帮助您轻松创建和管理磁盘目录。 DiskCatalogMaker支持多种磁盘格式&…

最长递增子序列,交错字符串

第一题&#xff1a; 代码如下&#xff1a; int lengthOfLIS(vector<int>& nums) {//dp[i]表示以第i个元素为结尾的最长子序列的长度int n nums.size();int res 1;vector<int> dp(n, 1);for (int i 1; i < n; i){for (int j 0; j < i; j){if (nums[i]…

R语言入门 | 使用 ggplot2 进行数据可视化

1.0准备工作 先下好tidyverse包&#xff0c;并进行加载。 install.packages ( "tidyverse" ) library(tidyverse) R 包只需安装一次&#xff0c;但每次开始新会话时都要重新加载。 1.1 数据框 数据框是变量&#xff08;列&#xff09;和观测&#xff08;行&#x…

高级数据结构-并查集

例题1&#xff1a; Alice和Bob玩了一个古老的游戏&#xff1a;首先画一个 &#x1d45b;&#x1d45b; 的点阵&#xff08;下图 n3 &#xff09;。 接着&#xff0c;他们两个轮流在相邻的点之间画上红边和蓝边&#xff1a; 直到围成一个封闭的圈&#xff08;面积不必为 1&#…

Leecode热题100--二分查找---33:搜索旋转排序矩阵

题目&#xff1a; 整数数组 nums 按升序排列&#xff0c;数组中的值 互不相同 。 给你 旋转后 的数组 nums 和一个整数 target &#xff0c;如果 nums 中存在这个目标值 target &#xff0c;则返回它的下标&#xff0c;否则返回 -1 。 思路&#xff1a; 此处采用容易理解的两次…

Make-An-Audio——用于语音生成的提示增强扩散模型

0.引言 论文提出了一个从文本生成语音的扩散模型 Make-An-Audio。该模型将文本提示作为输入&#xff0c;并据此生成语音。例如&#xff0c;输入 “一只猫在喵喵叫&#xff0c;一个年轻女人的声音”&#xff0c;就会输出猫在喵喵叫&#xff0c;一个女人在说话的音频。这项研究已…

php反序列化初步了解

一、定义 序列化&#xff08;串行化&#xff09;&#xff1a;将变量转换为可保存或传输的字符串的过程&#xff08;通常是字节流、JSON、XML格式&#xff09; 反序列比&#xff08;反串行化&#xff09;&#xff1a;把这个字符串再转化成原始数据结构或对象&#xff08;原来的…

一个生动的例子——通过ERC20接口访问Tether合约

生动的例子 USDT&#xff1a;符合ERC20标准的美元稳定币&#xff0c;Tether合约获得测试网上Tether合约地址通过自己写的ERC20接口访问这个合约 Tether合约地址&#xff1a;0xdAC17F958D2ee523a2206206994597C13D831ec7 IERC20.sol // SPDX-License-Identifier: GPL-3.0pra…

HTTP Basic Access Authentication Schema

HTTP Basic Access Authentication Schema 背景介绍流程安全缺陷参考 背景 本文内容大多基于网上其他参考文章及资料整理后所得&#xff0c;并非原创&#xff0c;目的是为了需要时方便查看。 介绍 HTTP Basic Access Authentication Schema&#xff0c;HTTP 基本访问认证模式…

代码随想录训练营Day 43|力扣343. 整数拆分、96.不同的二叉搜索树

1.整数拆分 代码随想录 视频讲解&#xff1a;动态规划&#xff0c;本题关键在于理解递推公式&#xff01;| LeetCode&#xff1a;343. 整数拆分_哔哩哔哩_bilibili 代码&#xff1a; class Solution { public:int integerBreak(int n) {// dp[i] 拆分数字i所获得的最大乘积为d…

7-zip工具?这么好用的你都能找到!

关于7-Zip&#xff0c;这不是一个神奇的小工具吗&#xff1f;让我悄悄告诉你&#xff0c;它其实是个压缩界的隐形冠军哦。 想象一下&#xff0c;你下载了一堆文件&#xff0c;电脑空间却告急&#xff0c;这时候7-Zip就像你的小助手&#xff0c;帮你把文件们“瘦身”&#xff0…

JavaScript-JavaWeb

目录 什么是JavaScript? js引入方式 js基础语法 书写语法 变量 数据据类型 运算符 类型转换 流程语句 js函数 js对象 1.Array 2.String 3.JSON js事件监听 什么是JavaScript? ● JavaScript(简称:JS)是一门跨平台、面向对象的脚本语言。是用来控制网页行为的,它能…

LeetCode2336无限集中的最小数字

题目描述 现有一个包含所有正整数的集合 [1, 2, 3, 4, 5, …] 。实现 SmallestInfiniteSet 类&#xff1a;SmallestInfiniteSet() 初始化 SmallestInfiniteSet 对象以包含 所有 正整数。int popSmallest() 移除 并返回该无限集中的最小整数。void addBack(int num) 如果正整数 …

Kong网关的负载均衡

安装java环境 查询 java安装包 196 yum list java* 安装java8197 yum install -y java-1.8.0-openjdk.x86_64 检验java8是否安装成功。198 java -version2个tomcat准备 另外一个tomcat区别在于&#xff1a;配置文件。conf/server.xml 启动tomcat [rootlocalhost bin]# ./…

如何在.htaccess文件创建一个自定义404页面

本周有一个客户&#xff0c;购买Hostease的虚拟主机&#xff0c;询问我们的在线客服&#xff0c;如何在.htaccess文件创建一个自定义404页面&#xff1f;我们为用户提供相关教程&#xff0c;用户很快解决了遇到的问题。在此&#xff0c;我们分享这个操作教程&#xff0c;希望可…

手摸手教你uniapp原生插件开发

行有余力,心无恐惧 这篇技术文章写了得有两三个礼拜,虽然最近各种事情,工作上的生活上的,但是感觉还是有很多时间被浪费.还记得几年前曾经有一段时间7点多起床运动,然后工作学习,看书提升认知.现在我都要佩服那会儿的自己.如果想回到那种状态,我觉得需要有三个重要的条件. 其…