javadoc == poor tool
I'm very disappointed with the tool.
1. There is no way to include documentation defined in other files. I don't want to let ALL documentation to stay in the source code. This makes code pretty much lost and hard to read behind documentation. Another reason is I don't want all technical writers to mock around the source code. Another reason is I want to be able to reuse useful pieces of documentation from time to time.
2. There is no way to include code examples from external files. I want to write my code examples as unit tests so I can compile and run them often to make sure they don't go stale. In those code examples I want to mark fragments that I actually want to include as code examples. Hand coding code examples in comments is a waste of time.
[783 byte] By [
romeok2a] at [2007-10-2 7:13:44]
How/where would you like the external documentation to appear?
As separate chapters? The MIF doclet does a wonderful job of
including external documents, by way of its XML book file:
http://java.sun.com/j2se/javadoc/mifdoclet/1.2/docs/xmlbookfile
Would you want something like this for the standard doclet?
We are slowly working on a spec for code examples:
http://www.javac.info/doc?n=JavaDoc.ExampleTag
-Doug
Thanks, the exampletag seems to be exactly what I'm looking for to build code examples.I also found a request to support the @include tag. This also looks like what I need. The only problem it was reported in 1999 and still in progress. Not sure if I can wait any longer :)
> Ugh, you are falling into the oldest trap in the
> book. Here is how to do it right.
> > System.out.println(javaDoc == poorTool); // returns
> false
> System.out.println(javaDoc.equals(poorTool)); //
> returns true
>
> Drake
System.out.println(javaDoc instanceof PoorTool); // returns true
