Custom doclet for 1.5 ?
I wrote a custom doclet in 1.2.2 a couple of years ago, and it's time to update everything to jdk 1.5. The custom doclet is very simple (not much different from Standard) but the 1.5 structure is extremely different from 1.2 .
When I wrote the 1.2 custom doclet, I had to copy all the java source, change the package names and customize the classes that needed it. Now I see that there is a separate directory structure for the doclet, and all the writers, etc. are under format/html.
Basically, all I need to do is slightly modify the overview-summary.html, and create an extra category of classes that are listed in package-summary.html and package-frame.html.
I have tried modifying various classes under format/html and including them in my jar file, but they don't seem to be picked up when I generate javadocs.
The Sun page that purportedly helps writing custom doclets explicitly states that the instructions it contains are valid for 1.2 .
http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/doclet/overview.html#custom
I can't find any recednt examples or instructions. Can someone give a quick overview of how to do this?
(Please do not post any replies concerning Docflex.)
[1235 byte] By [
KarenC123a] at [2007-10-3 6:24:52]
So you downloaded the doclet source from
http://www.sun.com/software/communitysource/j2se/java2/index.xml
modified the source files, compiled them to .class files, and replaced those files in tools.jar or creating another jar file? Replacing files tools.jar in should definitely work. Make sure you're loading that particular tools.jar file.
-Doug
Yes, that's basically what I did, I put them in a separate jar file and made sure that jar was first in my classpath. Today I'm going to try something else -- copy the files I need to change from html/format to my custom doclet folder and change as needed.
Well, I copied source from html\format into my doclet dir, compiled, made the jar, generated javadocs, and got this error, so I'll have to think of something else:javadoc: error - The Doclet Toolkit can only be used by com.sun.tools.doclets.formats.html.HtmlDoclet
Back to square one.
My custom doclet is in a package on the same level as Standard doclet. The custom doclet is cloned from Standard and is almost identifical to Standard (except for classname and package). I added a println statement to its start method.
I modified some source under formats\html. I added a println statement to HtmlDoclet start.
I compiled the custom doclet and everything under formats.html.
I built a jar file containing the custom doclet and all my classes under formats.html. The jar contents look fine and contains correct path names.
I generate javadocs with this command:
%java_home%\bin\javadoc -doclet com.sun.tools.doclets.customdoclet.CustomDoclet -docletpath c:\doclets1.5\customdoclet.jar -windowtitle "Test Wintitle" -public -doctitle "<h3>Test Doctitle</h3>" -d %javadocs% @publicapi.files
My console output includes the following. It does NOT include my println from my HtmlDoclet. I tried various settings for my classpath (with my custom jar file first, etc.) and I always get the same result.
*** starting CustomDoclet
Standard Doclet version 1.5.0_07
Building tree for all the packages and classes...
OK, I finally got it to work, but it is unbelievably kludgy. Here's what I had to do:
Make a copy of the jdk's tools.jar and save it so I can use it for non-javadoc purposes.
Add my custom classes to tools.jar using
c:\jdk1.5\bin\jar uvf tools.jar (etc.)
Make sure the output file is in the directory where the old tools.jar was.
Generate javadocs.
I could not get my customized files to tafe effect unless I actually replaced the files in the normal tools.jar. I think this is ridiculous but I thought I should let everybody know that this is how it works.
Yes, this is how it was designed. Modifying tools.jar is oe way to load a custom doclet.
There are two issues, and working around either one can solve this problem:
1) tools.jar gets loaded as part of the JDK, prior to anything on -classpath. Thus,
modifying the original tools.jar works fine. Putting a jar on the classpath will
not override it.
2) Sun implemented a lock-out in the doclet toolkit API to prevent others from using it
The idea was to develop the toolkit further to finalize it and then
remove the lock and make the API public. It's unknown when or if
Sun would remove this lock. Both the Standard and MIF doclets use the
doclet toolkit.
Each has its own workaround. For the first, you would have to run "java" (rather than "javadoc") on the custom doclet class -- then you can put customdoclet.jar ahead of tools.jar on classpath. For the second, you would have to modify the doclet toolkit to remove the lock-out, but then you'd still either have to modify the original tools.jar or call "java" instead of "javadoc" as described.
-Doug
