How to build javadoc from sources within a .jar file? - jar

Question

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?

Answer 1

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).