Javadoc question

[Martin Gregorie]

We are currently writing a series of regression tests for a complex
application. Each test extends a generic test class, itself a subclass
of JUnit, with inline code that creates a test message, inputs it and
then evaluates the results to generate a pass/fail evaluation.

We'd like to use javadoc to document the set of tests. This means that
we are uninterested in outputting anything except the class description
and two method descriptions - IOW we really, really don't need the links
to inherited classes and methods in the test documentation because its
just repetitive junk that is the same for every test and in any case is
already documented elsewhere as part of the testing engine.

Finally my questions:
- has anybody tried using javadoc this way
- were you able to suppress the list of inherited methods etc
- how did you do it.


TIA
Martin

 

[Roedy Green]

Finally my questions:
- has anybody tried using javadoc this way
- were you able to suppress the list of inherited methods etc

Read up on "doclets" they let you at the parsed JavaDoc to do with as
you please.

 

[Martin Gregorie]

Read up on "doclets" they let you at the parsed JavaDoc to do with as
you please.
>

I did so before asking this question. There seem to be no methods for
suppressing sections of the class page and no explicit support for
determining if a method is inherited or not unless you're expected to do
it by comparing the Doc representing the class a method is declared in
with the one you're processing: if there's a difference the method must
be inherited, but even then there's no obvious way of telling Javadoc to
skip it.

I get the distinct impression that doclets are for fiddling with
formatting but not for changing the output HTML structure.

I was hoping that somebody would have tried this and could confirm or
deny that it is possible.

 

[Stefan Ram]

I get the distinct impression that doclets are for fiddling with
formatting but not for changing the output HTML structure.

I have no knowledge about the possibilities of doclets,
but if everything else fails, you can post-process the
generated HTML documents.

For example a Perl-Script to adjust URIs in generated HTML
documents might read each document to a variable »$text«
and then modify this using lines such as the following.

$text =~ s{HREF="(.*?)"}{'HREF="' . rewrite( $path, $1 ). '"'}egi;
$text =~ s{<!--[^>]+-->\s*\n?}{}g;
$text =~ s{</HEAD>}{<BASE href="$base" />\n</HEAD>};

 

[Martin Gregorie]

I get the distinct impression that doclets are for fiddling with
formatting but not for changing the output HTML structure.

I have no knowledge about the possibilities of doclets,
but if everything else fails, you can post-process the
generated HTML documents.

For example a Perl-Script to adjust URIs in generated HTML
documents might read each document to a variable »$text«
and then modify this using lines such as the following.

$text =~ s{HREF="(.*?)"}{'HREF="' . rewrite( $path, $1 ). '"'}egi;
$text =~ s{<!--[^>]+-->\s*\n?}{}g;
$text =~ s{</HEAD>}{<BASE href="$base" />\n</HEAD>};

A good thought. Thanks.

For that matter it may be sensible to ignore javadoc and process the
source from scratch. All we really need is something like:

<h1>[test name]</h1>
Content of the initial comment

<h2>Setup details</h2>
Content of the setup method comment plus (possibly)
any comments inside the method.

<h2>Execution</h2>
Content of the run method comment plus (possibly)
any comments inside the method.

A parser to do this should be a pretty straight forward exercise by hand
or using Coco/R.

Like javadoc we need to walk the package directory structure to find the
tests and, while doing that, generate index page(s) for the test
packages and the tests within each package, but that's also easy to do.