发布Java库时为何要同时提供javadoc.jar和sources.jar？

通常发布Java库时，建议同时提供sources.jar和javadoc.jar，两者的适用场景完全不同，javadoc.jar确实存在不少sources.jar无法实现的能力：

• 离线独立查阅：sources.jar中的文档注释嵌在源码内，查看必须依赖IDE的解析能力，或是手动翻阅源码。而javadoc.jar是预编译完成的静态HTML文档包，解压后直接用浏览器就能打开，不需要安装JDK、IDE，也不需要关联源码，哪怕只是临时查接口定义，不用打开开发环境就能快速查阅，非常适配离线场景、非开发人员快速参考的需求。
• 结构化全局展示：javadoc在生成时会自动完成结构化整理，比如自动生成类继承关系、所有方法/字段的索引页、包级总览文档、跨类的引用跳转，还支持自定义全局的框架概述、快速入门导引、示例代码汇总等内容。这些全局结构化内容如果只看零散的源码注释，需要手动逐个类翻阅，根本无法快速获取整体架构信息，尤其对于大型框架类库，javadoc的全局汇总能力优势非常明显。
• 富文本格式完整渲染：javadoc支持大量自定义标签，比如@since标注首次引入的版本、@deprecated标注废弃说明和替代方案，还支持插入HTML格式的说明、高亮示例代码、表格、图片等富文本内容。这些内容虽然也写在源码注释里，但IDE的悬浮提示大多无法完整解析展示，比如复杂表格、自定义格式经常出现错乱，而预编译的javadoc可以完整渲染所有格式，可读性高很多。
• 适配无源码分发场景：部分商用内部库、有限分发的闭源库，并不适合对外暴露完整源码，这种场景下只分发二进制包+javadoc.jar就能提供完整的文档支持，完全不需要泄露源码，这是sources.jar不可能实现的。
• 适配自动化文档工具：绝大多数API文档聚合平台、企业内部的依赖管理系统，都支持直接识别javadoc.jar自动生成在线文档，不需要上传源码。如果只有sources.jar，这类工具大多无法直接提取文档内容，需要额外做转换处理。

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