如何从 .jar 文件中的源构建 javadoc？答案

【问题标题】：How to build javadoc from sources within a .jar file?如何从 .jar 文件中的源构建 javadoc？
【发布时间】：2011-01-22 06:11:02
【问题描述】：

我必须从包含源文件和类文件的 myCode.jar 构建 Javadoc。我可以不提取罐子吗？

根据http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#classpath，我应该可以这样做：C:\>javadoc -d docs -classpath myCode.jar net\kem\jmx\CacheManagerMBean.java 但是，我收到以下错误：

javadoc: error - File not found: "net\kem\jmx\CacheManagerMBean.java"
[search path for source files: [myCode.jar]]
[search path for class files: [C:\Program Files\Java\jdk1.5.0_17\jre\lib\rt.jar, C:\Program Files\Java\jdk1.5.0_17\jre\lib\jsse.jar,
 C:\Program Files\Java\jdk1.5.0_17\jre\lib\jce.jar, C:\Program Files\Java\jdk1.5.0_17\jre\lib\charsets.jar, C:\Program Files\Java\jd
k1.5.0_17\jre\lib\ext\dnsns.jar, C:\Program Files\Java\jdk1.5.0_17\jre\lib\ext\localedata.jar, C:\Program Files\Java\jdk1.5.0_17\jre
\lib\ext\sunjce_provider.jar, C:\Program Files\Java\jdk1.5.0_17\jre\lib\ext\sunpkcs11.jar, C:\Projects\RenderClusterController\WebCo
ntent\WEB-INF\lib\makoRenderJMX.jar]]
[done in 360 ms]
1 error

看来，javadoc 在 jar 中找不到源文件。我相信消息来源就在那里。

有什么建议吗？

【问题讨论】：

仔细检查 jar 是否确实包含源文件（将其作为 zip 文件打开）您可能还想尝试将 net\kem... 调整为点而不是 \ 或完全删除它

标签： jar documentation javadoc

【解决方案1】：

一些初步测试表明它不起作用（至少在我这里有的 OpenJDK 1.6.0_20 上）。

所以，我查看了源代码（可在 mercurial web-interface 中浏览）。 Javadoc（在那里的版本，可能与我这里的版本不同）在其操作中使用了相当多的 Javac，看起来两者都使用javax.tools.JavaFileManager 接口来实现对其源文件的访问，特别是在子接口StandardJavaFileManager。

This interface 声称能够访问 zip 文件条目：

此文件管理器创建代表常规文件、zip 文件条目或类似文件系统的基于容器中的条目的文件对象。

但这里是如何使用的（JavaDocTool.getRootDocImpl()）：

  148                 String name = it.head;
  149                 if (!docClasses && name.endsWith(".java") && new File(name).exists()) {
  150                     JavaFileObject fo = fm.getJavaFileObjects(name).iterator().next();
  151                     docenv.notice("main.Loading_source_file", name);
  152                     JCCompilationUnit tree = parse(fo);
  153                     classTrees.append(tree);
  154                 } else if (isValidPackageName(name)) {
  155                     names = names.append(name);
  156                 } else if (name.endsWith(".java")) {
  157                     docenv.error(null, "main.file_not_found", name);
  158                 } else {
  159                     docenv.error(null, "main.illegal_package_name", name);
  160                 }

第一种情况适用于您使用.java 文件的调用 - 但由于它在文件系统中不作为文件存在（new File(name).exists() 返回 false），这无济于事，您将获得第三种情况出现“找不到文件”错误的情况。

用更合适的条件替换此条件（如!fm.getJavaFileObjects(name).isEmpty() - 前提是上下文是用实际上在 jar/zip 文件中查找的 JavaFileManager 初始化的，但我现在没有检查。

看起来它可以工作。

因此，您必须解压缩源 jar，或修补 javac 实现（最好将其贡献给主 javac 源）。

【讨论】：