Home | Contact Us | FAQ | Search & Site Map | Link to Us
Sign In | Join | Other 45 Sites in Network
HomeAnnouncementsWhite Papers
Discussion GroupsFirst AidDatabasesJavaBeansGUIJava 3DVirtual MachineCORBASecurityToolsGeneral
Java DirectoryOpen Source ProjectsSample Book ChaptersUser GroupsWeb Resources
Related Topics
Databases.NETMore Topics ...

Java Forum / General / March 2008

Tip: Looking for answers? Try searching our database.

Javadoc question

Thread view: 
Martin Gregorie - 05 Mar 2008 21:35 GMT
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

Signature

martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

Roedy Green - 06 Mar 2008 01:28 GMT
On Wed, 05 Mar 2008 21:35:34 +0000, Martin Gregorie
<martin@see.sig.for.address> wrote, quoted or indirectly quoted
someone who said :

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

Roedy Green Canadian Mind Products
The Java Glossary
http://mindprod.com
Martin Gregorie - 08 Mar 2008 01:15 GMT
> On Wed, 05 Mar 2008 21:35:34 +0000, Martin Gregorie
> <martin@see.sig.for.address> wrote, quoted or indirectly quoted
[quoted text clipped - 6 lines]
> 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.

Signature

martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

Stefan Ram - 08 Mar 2008 02:19 GMT
>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 - 08 Mar 2008 11:03 GMT
>> I get the distinct impression that doclets are for fiddling with
>> formatting but not for changing the output HTML structure.
[quoted text clipped - 10 lines]
> $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.

Signature

martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |



Free Magazines

Get these publications absolutely FREE for up to 12 months. There are no hidden fees and no obligation. Simply choose a title, complete the application form and submit it. Read more ...

Oracle MagazineNetwork ComputingComputer WorldBio-IT WorldeWeekInformation WeekInfosecurity
 
Sign In
Join
My Latest Posts
My Monitored Threads
My Blog
My Photo Gallery
My Profile
My Homepage

Start New Thread
Enable EMail Alerts
Rate this Thread



©2008 Advenet LLC   Privacy Policy - Terms of Use
This website includes both content owned or controlled by Advenet as well as content owned or controlled by third parties.