Skip to Main Content

Java APIs

Announcement

For appeals, questions and feedback about Oracle Forums, please email oracle-forums-moderators_us@oracle.com. Technical questions should be asked in the appropriate category. Thank you!

non-HTML Javadoc

843810Nov 17 2004 — edited Dec 11 2004
At the reasearch laboratory I am studying for my Master degree, we want to document our Java code in LaTeX for highly mathematical packages. LaTeX is the most powerful environment for math and it can be used to produce good-looking PDF. With standard Javadoc, there is nothing free for PDF. The MIFF doclet is totally useless since we do not have Framemaker. PDFDoclet is good, but it discards almost all HTML formatting. TexDoclet produces output that is too different from standard Javadoc and only supports a subset of HTML, no math can be formatted with that. We can use, in HTML, special characters and maybe MathML, but we want to have math in PDF too. The first solution was to write the Java code and documentation in .tex files. Some special LaTeX commands were used to delimit the code and an ad hoc Perl script was extracting the Java code and converting the LaTeX for documentation into Javadoc-style comments. This script was complex and could bug at any time since I am not an expert in text parsing. The .java file were used to compile the classes and generate HTML documentation whereas the .tex files were intended for printed PDF documentation. This solution was not perfect because it gets debugging Java code harder and prevents text editors from auto-indenting source code. When an exception occurs, we only know the line number in the corresponding Java class and this information is not contained in the .tex source file.
So I made a second system during the last summer. This time, the main files are the .java, with LaTeX in Javadoc comments! With a special Javadoc doclet, I could successfully extract these contents and put them in LaTeX files intended for documentation. These LaTeX files have different filenames (file Foo.java has a corresponding Foodoc.tex, preventing any name clash with the old system). For the HTML doc, things got thrickier. I could go over the problem by creating a special doclet that extracts every LaTeX documentation comment, put that in a huge LaTeX file, convert to HTML, get back the result and put that in Doc comments. To do this, I simply use the setRawTextComment method of the Doc interface. After the Doc comments were ready, I was forwarding the RootDoc to the Standard Doclet. This worked fine with JDK 1.4.2, except it was longer to build my Javadoc because of the LaTeX to HTML translation.
Now, with JDK 1.5.0, all my work is gone! The setRawTextComment method of the Doc interface does not work as expected and simply ignores my new comment strings (with a warning saying that multiple sources of comments were found), which shoots LaTeX into my HTML files.
All solutions I imagined are uninteresting or too complex. First, I could rewrite the whole Javadoc tool to feed the Standard Doclet with my generated HTML. This approach is undoable for me because parsing the Java files is way too complex and it will simply never work since I do not want to spend months on that. I thought about reimplementing the Doclet API interfaces but this too requires a lot of work. I also saw an alternative to Javadoc, called XJavadoc, but this tool uses a completely different doclet API, which would require me to entirely rewrite my actual doclets. The XJavadoc's documentation is not as clear as Javadoc's, too. I could extract the LaTeX comments from Java files, convert that and generate new Java files to feed them to Javadoc, but this too would require parsing the Java files and will be hard to make working properly. The Javadoc tool cannot help for the translation if source files I would need to be generated because it does not give access to the source code from the RootDoc interface.
I know this is not an ideal setup to put LaTeX documentation in Javadoc comments, but if I do not do that, I will have to write my Java code in .tex files and loose all the auto-indentations features of any text editor. I do not know what to do and I would like a better solution than to stick with JDK 1.4 since I intend to adapt my doclets for them to support the 1.5 new constructs.
Comments
Locked Post
New comments cannot be posted to this locked post.
Post Details
Locked on Jan 8 2005
Added on Nov 17 2004
4 comments
516 views