Java 笔记 07：包机制，JavaDoc 文档的生成方式，Math 工具类，以及字符串连接符相关内容

一、前言

记录时间 [2024-04-25]

系列文章简摘：
Java 笔记 01：Java 概述，MarkDown 常用语法整理
Java 笔记 04：Java 数据类型基础，数据类型转换，及其相关场景拓展
Java 笔记 05：变量和常量相关知识，Java 编程的命名规范
Java 笔记 06：基本运算符概述，分类，和使用方式

更多 Java 相关文章，请参考上面专栏哦。

本文详细介绍了 Java 包机制，以及如何使用 CMD / IDEA 方式生成 JavaDoc 文档。此外，还整理了数学工具类 Math 的使用，拓展了字符串连接符相关内容。

二、包机制

1. 概述

包机制在编程中是一种组织代码的方式，用于将相关的类、接口、枚举和注解组织在一起。这有助于模块化代码，使其更易于管理和重用。

在 Java 中，包由关键字 package 定义，通常位于 Java 文件的顶部。包名是以点 . 分隔的标识符序列，例如：com.example.myapp 是包名。

// 包名 com.example.myapp
package com.example.myapp;

---

2. 作用

包机制 package 用于区分 类 Class 的命名空间，一般使用公司域名倒置作为包名。

使用包机制的优点如下：

1. 组织性：可以将相关的类和接口组织在一起，使项目结构更加清晰。
2. 封装性：可以限制类的可见性，有助于实现信息隐藏和封装。
3. 重用性：允许将代码模块化，使其可以在不同的项目中重用。
4. 命名空间：提供了一个命名空间，避免了命名冲突，特别是当使用第三方库或框架时。

---

3. 创建和使用

创建和使用包，需在 Java 文件的顶部添加 package 声明，然后在其他文件中使用 import 语句来导入需要的类或接口。

注意：导入的类名不能与当前的类名重复！

例如：

// 文件路径: com/example/myapp/MyClass.java
package com.example.myapp;

// 在其他文件中使用，用 import 导入
import com.example.myapp.MyClass;

// * 通配符：导入这个包下所有的类
import com.example.myapp.*;

---

更多编程规范，请参考：阿里巴巴 Java 开发手册。

三、JavaDoc 生成文档

1. API 文档概述

详细的 API 官方文档，请查看：Java SE API 官方在线文档。

javadoc 是 Java 开发工具包 JDK 中的一个命令行工具，用于从 Java 源代码文件生成 API 文档。这些生成的文档通常以 HTML 格式呈现，提供了对类、方法、字段等的详细描述，以及相应的注释。

使用 javadoc 工具，可以为 Java 代码添加特殊的注释（称为 Javadoc 注释），这些注释使用特定的标记（如 @param、@return、@throws 等）来描述代码的各个部分。这样，javadoc 工具就可以根据这些注释生成详细的文档。

javadoc 命令用来生成自己的 API 文档，可以添加的参数有：

• @author：作者名
• @version：版本号
• @since：指明需要最早使用的 jdk 版本
• @param：参数名
• @return：返回值情况
• @throws：抛出异常情况

2. 生成 API 文档

生成 API 文档有两种方式，一种是命令行 javadoc 方式，另一种是借助集成开发工具 IDEA。

编写测试类

使用 Java 编写一个简单的类，用于展示如何使用 Javadoc 注释。

• 写在类上面的，是类的注释；
• 写在方法上面的，是方法的注释。

package com.example.myapp;

/**
 * 这是一个简单的类，用于展示如何使用 Javadoc 注释。
 *
 * @author yuanyuan
 * @data 2024/4/24
 * @description JavaDoc 学习
 * @version 1.0
 * @since 1.8
 */

public class MyClass {
    
    // 一个属性
    String name;

    /**
     * 这是一个简单的方法，用于添加两个整数。
     *
     * @param a 第一个整数
     * @param b 第二个整数
     * @return 两个整数的和
     */
    public int add(int a, int b) {
        return a + b;
    }
    
    /**
     * 这是一个简单的方法，可以抛出异常
     *
     * @param name
     * @return name 的值
     * @throws Exception
     */
    public String test(String name) throws Exception {
        return name;
    }
}

使用命令行生成

使用 CMD 打开命令行窗口，找到 MyClass.java 文件所在目录，执行 javadoc 命令：

• 使用 UTF-8 编码可以解决中文乱码问题。

# encoding 设置编码为 UTF-8
# charset  设置字符集编码为 UTF-8

javadoc -encoding UTF-8 -charset UTF-8 MyClass.java

javadoc 命令执行完成后，MyClass.java 文件所在目录会新增很多文件，就是生成的 JavaDoc 文档。

其中，index.html 是文档入口，双击打开查看：

---

查看类：

---

查看方法：

使用 IDEA 生成

用 IDEA 生成 javaDoc 文档的方式：选中 package ==> Tools ==> Generate JavaDoc

---

选择生成的范围：

---

设置文档输出的位置和参数：

---

设置语言和字符集：勾选在浏览器中打开。

四、Math 类的使用

java.lang.Math 类提供了一系列用于执行基本数学运算的静态方法。以下是 Math 类的一些常用方法及其用法。

1. 常数

• Math.PI：圆周率，约等于 3.14159。
• Math.E：自然对数的底，约等于 2.71828。

---

2. 数学运算

• Math.abs(x)：返回 x 的绝对值。
• Math.ceil(x)：返回大于或等于 x 的最小整数。
• Math.floor(x)：返回小于或等于 x 的最大整数。
• Math.round(x)：返回 x 最接近的整数，四舍五入。

---

3. 指数和对数

• Math.exp(x)：返回自然数 e 的 x 次幂。
• Math.log(x)：返回 x 的自然对数。
• Math.log10(x)：返回 x 的以 10 为底的对数。
• Math.pow(x, y)：返回 x 的 y 次幂。

---

4. 三角函数

• Math.sin(x)， Math.cos(x)，Math.tan(x)：分别返回 x 的正弦、余弦和正切值。
• Math.asin(x)，Math.acos(x)，Math.atan(x)：分别返回 x 的反正弦、反余弦和反正切值。
• Math.atan2(y, x)：返回从 x 轴正向到点 (x, y) 之间的角度。

---

5. 其他

• Math.sqrt(x)：返回 x 的平方根。
• Math.max(x, y)：返回 x 和 y 中的最大值。
• Math.min(x, y)：返回 x 和 y 中的最小值。
• Math.random()：返回一个大于或等于 0.0 且小于 1.0 的随机浮点数。

---

6. 使用示例

以下是 Math 类的一些常用方法在 Java 程序中的具体应用：

public class MathExample {
    public static void main(String[] args) {
        double a = 25.5;
        double b = -15.7;
        
        // 计算绝对值
        System.out.println("Absolute value of a: " + Math.abs(a));
        
        // 向上取整
        System.out.println("Ceil value of a: " + Math.ceil(a));
        
        // 向下取整
        System.out.println("Floor value of a: " + Math.floor(a));
        
        // 四舍五入
        System.out.println("Round value of a: " + Math.round(a));
        
        // 计算平方根
        System.out.println("Square root of a: " + Math.sqrt(a));
        
        // 最大值
        System.out.println("Max value between a and b: " + Math.max(a, b));
        
        // 最小值
        System.out.println("Min value between a and b: " + Math.min(a, b));
        
        // 随机数
        System.out.println("Random number: " + Math.random());
        
        // 计算幂指数，如 2 的 3 次方
        System.out.println("2^3 = " + Math.pow(2,3));
    }
}

五、字符串连接符

在 Java 中，可以使用 + 运算符来连接字符串。

值得注意的是，当字符串连接符的位置发生改变时，输出的结果也有可能不同。

具体参考如下案例：定义 a 和 b，a + b 的值为 30，当 a + b 与字符串进行拼接时：

• 空字符串拼接在前面：""+a+b，输出结果为 1020，这是因为 a 和 b 被转换成了字符串；
• 空字符串拼接在前面，但 a+b 加括号：""+ (a+b)，输出结果为 30；
• 空字符串拼接在后面：a+b+""，输出结果为 30；

int a = 10;
int b = 20;

// 字符串连接符   +   , String
// 比较
System.out.println(a+b);        	//30
System.out.println(""+a+b);     	//1020
System.out.println(""+ (a+b) ); 	//30
System.out.println(a+b+"");     	//30

六、总结

本文详细介绍了 Java 包机制，以及如何使用 CMD / IDEA 方式生成 JavaDoc 文档。此外，还整理了数学工具类 Math 的使用，拓展了字符串连接符相关内容。

一些参考资料

狂神说 Java 零基础：https://www.bilibili.com/video/BV12J41137hu/
TIOBE 编程语言走势： https://www.tiobe.com/tiobe-index/
Typora 官网：https://www.typoraio.cn/
Oracle 官网：https://www.oracle.com/
Notepad++ 下载地址：https://notepad-plus.en.softonic.com/
IDEA 官网：https://www.jetbrains.com.cn/idea/
Java 开发手册：https://developer.aliyun.com/ebook/394
Java 8 帮助文档：https://docs.oracle.com/javase/8/docs/api/