Javadoc 是 Java 提供的一种工具，用于从 Java 源代码中的注释生成 API 文档

1. 什么是 Javadoc？

Javadoc 是 Java 提供的一种工具，用于从 Java 源代码中的注释生成 API 文档。它使用特殊的注释格式（以 /** ... */ 包围）来描述类、方法、字段等，并生成 HTML 格式的文档，供开发者查阅。

---

2. 为什么需要查看 Javadoc？

• 了解 API 用法：查看类、方法的详细说明和示例。
• 提高开发效率：快速查找和使用第三方库的功能。
• 学习最佳实践：通过官方文档学习代码设计和实现方式。

---

3. 如何查看 Javadoc？

(1) 在线查看

许多开源库和框架提供了在线 Javadoc 文档。例如：

• Java 标准库：https://docs.oracle.com/javase/8/docs/api/
• Spring Framework：https://docs.spring.io/spring-framework/docs/current/javadoc-api/

(2) 本地查看

如果项目依赖的库包含 Javadoc，可以通过 IDE 或命令行查看。

---

4. 在 IDE 中查看 Javadoc

(1) IntelliJ IDEA

• 将鼠标悬停在类或方法上，会自动显示 Javadoc。
• 使用快捷键 Ctrl + Q（Windows/Linux）或 F1（Mac）查看详细文档。
• 在项目依赖中右键点击库，选择 Download Sources 和 Download Javadoc。

(2) Eclipse

• 将鼠标悬停在类或方法上，会自动显示 Javadoc。
• 使用快捷键 F2 查看详细文档。
• 在项目依赖中右键点击库，选择 Properties > Javadoc Location 配置 Javadoc 路径。

(3) Visual Studio Code

• 安装 Java 扩展包（如 Extension Pack for Java）。
• 将鼠标悬停在类或方法上，会自动显示 Javadoc。
• 使用快捷键 Ctrl + Shift + P，输入 Java: Open Javadoc 查看详细文档。

---

5. 在命令行中生成和查看 Javadoc

(1) 生成 Javadoc

使用 javadoc 命令从源代码生成 Javadoc。例如：

javadoc -d docs -sourcepath src -subpackages com.example

• -d docs：指定输出目录。
• -sourcepath src：指定源代码目录。
• -subpackages com.example：指定要生成文档的包。

(2) 查看 Javadoc

生成后，打开 docs/index.html 文件即可查看 Javadoc。

---

6. 在 Maven 项目中查看 Javadoc

(1) 生成 Javadoc

在 pom.xml 中配置 maven-javadoc-plugin：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.3.1</version>
        </plugin>
    </plugins>
</build>

运行以下命令生成 Javadoc：

mvn javadoc:javadoc

(2) 查看 Javadoc

生成后，打开 target/site/apidocs/index.html 文件即可查看。

---

7. 在 Gradle 项目中查看 Javadoc

(1) 生成 Javadoc

在 build.gradle 中配置 javadoc 任务：

task generateJavadoc(type: Javadoc) {
    source = sourceSets.main.allJava
    destinationDir = file("docs/javadoc")
}

运行以下命令生成 Javadoc：

gradle generateJavadoc

(2) 查看 Javadoc

生成后，打开 docs/javadoc/index.html 文件即可查看。

---

8. 最佳实践

• 为代码添加 Javadoc：养成良好的注释习惯，方便他人使用。
• 下载依赖的 Javadoc：在 IDE 中配置依赖的 Javadoc，方便查阅。
• 定期生成和发布 Javadoc：为项目维护最新的 API 文档。

---

9. 总结

Javadoc 是 Java 开发者不可或缺的工具，它通过生成详细的 API 文档，帮助开发者快速理解和使用代码。无论是通过 IDE、命令行还是构建工具，查看 Javadoc 都非常简单。掌握 Javadoc 的使用方法，不仅能提高开发效率，还能提升代码的可维护性和可读性。
1 package org.apache.maven.plugins.ejb;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * “License”); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 /
21
22 import java.io.File;
23
24 /*
25 * This class contains some helper methods which do not belong to {@link EjbMojo}.
26 *
27 *

28   * Think about this helper class, cause i’ve got the impression this can be made better.

29   * 

30 *
31 * @author Karl Heinz Marbaise
32 /
33 public final class EjbHelper
34 {
35 private EjbHelper()
36 {
37 // prevent instantiation
38 }
39
40 /*
41 * Check if a classifier is valid or not.
42 *
43 * @param classifier The classifier which should be checked.
44 * @return true in case of a valid classifier false otherwise which includes the case where
45 * classifier is {@code null}.
46 /
47 public static boolean isClassifierValid( String classifier )
48 {
49 // @FIXME: Check classifier for trailing dash? “a-0” valid?
50 // What are the rules for a valid classifier? Somewhere documented? which can be used as a reference?
51 boolean result = false;
52
53 // The following check is only based on an educated guess 😉
54 if ( hasClassifier( classifier ) && classifier.matches( "¹+[0-9a-zA-Z\-]" ) )
55 {
56 result = true;
57 }
58
59 return result;
60 }
61
62 /**
63 * Check if the given classifier exists in the meaning of not being {@code null} and contain something else than
64 * only white spaces.
65 *
66 * @param classifier The classifier to be used.
67 * @return true in case when the given classifier is not {@code null} and contains something else than white spaces.
68 /
69 public static boolean hasClassifier( String classifier )
70 {
71 boolean result = false;
72 if ( classifier != null && classifier.trim().length() > 0 )
73 {
74 result = true;
75 }
76 return result;
77 }
78
79 /*
80 * Returns the Jar file to generate, based on an optional classifier.
81 *
82 * @param basedir the output directory
83 * @param finalName the name of the ear file
84 * @param classifier an optional classifier
85 * @return the file to generate
86 */
87 public static File getJarFile( File basedir, String finalName, String classifier )
88 {
89 if ( basedir == null )
90 {
91 throw new IllegalArgumentException( “basedir is not allowed to be null” );
92 }
93 if ( finalName == null )
94 {
95 throw new IllegalArgumentException( “finalName is not allowed to be null” );
96 }
97
98 StringBuilder fileName = new StringBuilder( finalName );
99
100 if ( hasClassifier( classifier ) )
101 {
102 fileName.append( “-” ).append( classifier );
103 }
104
105 fileName.append( “.jar” );
106
107 return new File( basedir, fileName.toString() );
108 }
109
110 }

---

1. a-zA-Z ↩︎