如何从.jar文件中的源构建javadoc？ [英] How to build javadoc from sources within a .jar file?

问题描述

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

根据 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  - 找不到文件：net\kem \jmx\CacheManagerMBean.java
 [源文件的搜索路径：[myCode.jar]] 
 [类文件的搜索路径：[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：\程序文件\Java\jdk1.5.0_17\jre\lib\jce.jar，C：\Program Files\Java\jdk1.5.0_17\jre\lib\charsets.jar， C：\P rogram 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]] 
 [在360毫秒内完成] 
 1错误
  

看来，javadoc找不到jar中的源文件。我有信心来源在那里。

任何建议？

解决方案

有些第一个测试表明它不起作用（至少在OpenJDK 1.6.0_20，我在这里）。

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

此界面声称能够访问zip文件条目：

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

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

  148 String name = it.head; 
 149 if（！docClasses&&  name.endsWith（。java）&& new File（name）.exists（））{
 150 JavaFileObject fo = fm.getJavaFileObjects ）.iterator（）下（）; 
 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（） - 提供的上下文是用JavaFileManager初始化的，其实际上在jar / zip文件中，现在没有检查。

所以，你可以打开你的源代码jar，或者修补你的javac实现（最好把它作为主javac源） / p>

I have to build Javadoc from myCode.jar that contains both sources and class files. Can I do it without extracting the jar?

According to http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#classpath I should be able to do so this way: C:\>javadoc -d docs -classpath myCode.jar net\kem\jmx\CacheManagerMBean.java However, I get the following error:

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

It seems, javadoc cannot find the source files within the jar. I'm confident that the sources are there.

Any suggestions?

解决方案

Some first tests indicate it does not work (at least on OpenJDK 1.6.0_20, which I have here).

So, I looked into the source (browsable in a mercurial web-interface). Javadoc (in the version there, which may differ from the one I have here) uses quite some bits of Javac in its for the operation, and it looks like both are using the javax.tools.JavaFileManager interface to implement access to their source files, specifically in the subinterface StandardJavaFileManager.

This interface claims to be able to access zip file entries:

This file manager creates file objects representing regular files, zip file entries, or entries in similar file system based containers.

But here how it is used (in 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                 }

The first case would apply in your call with a .java file - but since it does not exist as a file in the file system (new File(name).exists() returns false), this does not help, and you get instead the third case with a "file not found" error.

It looks like it could work when replacing this condition with a more suitable one (like !fm.getJavaFileObjects(name).isEmpty() - provided the context is initialized with a JavaFileManager which in fact looks in jar/zip files, which I did not check now.

So, you'll have either to unpack your source jar, or patch your javac implementation (preferably contributing this to the main javac source).

这篇关于如何从.jar文件中的源构建javadoc？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！