如何将Javadoc包含进Java库JAR包中？

一、基础编写与编译 #

1. 编写库代码
   按规范定义包结构（比如com.yourid.yourlib），给类和核心方法添加标准Javadoc注释，示例：

   /**
    * 字符串工具类，提供常用字符串处理方法
    */
   package com.solus.examplelib;
   
   public class StringUtils {
       /**
        * 将输入字符串转为大写并追加指定后缀
        * @param input 待处理的原始字符串
        * @param suffix 要追加的后缀内容
        * @return 处理后的结果字符串
        */
       public static String upperWithSuffix(String input, String suffix) {
           return input.toUpperCase() + suffix;
       }
   }
   

2. 编译class文件
   使用javac命令指定输出目录，避免源码和class文件混放：

   javac -d bin src/com/solus/examplelib/*.java
   

   执行后，bin目录下会生成对应包结构的.class文件。

二、Javadoc的生成与关联 #

你疑惑的Javadoc问题：普通注释确实不会被编译进class文件，JDK的文档是单独生成的Javadoc包，和核心类库JAR关联使用的，不是编译在一起的。

生成Javadoc并打包：

1. 生成HTML格式的Javadoc文档：

   javadoc -d docs -sourcepath src com.solus.examplelib
   

2. 将Javadoc打包成单独的JAR：

   jar cvf examplelib-javadoc.jar -C docs .
   

另外，建议同时打包源码JAR，方便查看源码：

jar cvf examplelib-sources.jar -C src .

三、正确打包可使用的库JAR #

你之前打包源码JAR没用，因为IntelliJ需要编译后的.class文件才能识别类。打包主库JAR的命令：

jar cvf examplelib.jar -C bin .

这个JAR里包含编译好的class文件，是伙伴导入后能直接使用的核心文件。

最终你应该有三个文件：

• examplelib.jar：核心类文件包
• examplelib-sources.jar：源码包
• examplelib-javadoc.jar：文档包

四、IntelliJ导入与文档配置 #

导入主JAR后，还要关联源码和Javadoc才能正常使用：

1. 打开Project Structure（快捷键：Ctrl+Alt+Shift+S）
2. 左侧选择Libraries，找到你添加的外部库
3. 在右侧面板点击Attach Sources...，选择examplelib-sources.jar
4. 点击Attach Documentation...，选择examplelib-javadoc.jar

配置完成后，就能在代码中导入类（比如import com.solus.examplelib.StringUtils;），鼠标悬停方法时也会显示Javadoc注释。

五、分发与伙伴使用 #

把三个JAR打包成压缩包发给伙伴，附上简单说明：

1. 导入examplelib.jar作为外部库
2. 按上述步骤关联源码和Javadoc包
   如果后续用Maven/Gradle管理，还可以把库发布到本地或私有仓库，伙伴只需在构建文件中添加依赖即可，无需手动导入JAR。

内容的提问来源于stack exchange，提问作者Solus Bellator