Java包机制及javadoc详解

下面是“Java包机制及javadoc详解”的完整攻略。

一、Java包机制

Java中的包（Package）是将相关的类组成的一种单元，它的作用就是解决了相同类名的问题，也方便了其他开发人员的使用。在Java中，每一个类都必须属于一个包，没有包名的类默认属于默认包。

1.1 包的定义

我们可以使用package关键字定义一个包，它必须放在类定义之前。语法格式如下：

package com.example.mypackage;

其中，com.example.mypackage是包的名称，可以根据业务需要自定义，包名通常都是小写字母。

1.2 包的引用

引用包中的类有两种方式：

• 使用全限定类名（qualified class name）：包名+类名
• 使用import关键字引入类

使用全限定类名：

com.example.mypackage.MyClass obj = new com.example.mypackage.MyClass();

使用import关键字：

import com.example.mypackage.MyClass;
//...
MyClass obj = new MyClass();

1.3 包的命名规范

包名的命名规范是com + 公司/组织名 + 项目名/模块名，其中，公司/组织名和项目名/模块名都可以用小写字母和数字组合而成，用小写字母将它们隔开。如：

com.example.myproject

二、javadoc详解

javadoc是Java中的一个工具，用于生成文档，它可以通过简单的注释标记为程序中的方法和类中的内容生成HTML文档。

2.1 注释类型

Java中有3种注释类型：

• /**...*/ ：用于javadoc文档注释
• /*...*/ ：普通的多行注释
• //... ：单行注释

2.2 javadoc注释标记

javadoc注释标记由一个@符号开始，然后添加一个标记名称，后面跟着一些文本描述。常见的标记有：

• @param：方法参数的描述
• @return：方法的返回值的描述
• @exception或@throws：方法能够抛出的异常的描述

示例：

/**
 * 获取两个数的和
 * @param a 第一个数
 * @param b 第二个数
 * @return 两个数的和
 */
public static int add(int a, int b) {
    return a + b;
}

2.3 生成文档

使用javadoc工具生成文档，首先需要设置好CLASSPATH环境变量，然后在命令行中执行如下命令：

javadoc -d [文档路径] [包名]

其中，文档路径是指生成的文档存放的路径，包名是指要生成文档的包名。例如：

javadoc -d ./doc com.example.mypackage

三、示例

最后，我们来看两个示例。

示例一：定义包和类

package com.example.mypackage;

/**
 * 人类信息类
 */
public class Person {
    /**
     * 姓名
     */
    private String name;

    /**
     * 年龄
     */
    private int age;

    /**
     * 构造方法
     * @param name 姓名
     * @param age 年龄
     */
    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    /**
     * 获取姓名
     * @return 姓名
     */
    public String getName() {
        return name;
    }

    /**
     * 获取年龄
     * @return 年龄
     */
    public int getAge() {
        return age;
    }

    /**
     * 设置年龄
     * @param age 年龄
     */
    public void setAge(int age) {
        this.age = age;
    }
}

示例二：生成文档

在命令行中执行如下命令：

javadoc -d ./doc com.example.mypackage

执行完毕后，在doc目录下会生成相应的API文档。