cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Guido Casper <gcas...@s-und-n.de>
Subject Javadocs for published classes/interfaces
Date Tue, 25 May 2004 13:18:03 GMT
Hi all,

I just committed a new Ant task that generates javadocs only for 
classes/interfaces tagged with:
@cocoon.usage  published

Just execute
build published-api

what you get is:
build\cocoon-2.2.0-dev\published-api-xml
(containing the Javadocs in XML format corresponding to QDoxSource)

and:
build\cocoon-2.2.0-dev\published-api-html
(transformed via Ant's xslt task)

These will be mostly empty of course as there are no such tags yet 
(which I hereby propose to introduce :-).

This may (now or later) easily be extended to generate javadocs for:
@cocoon.usage  flowscript
or similar.

At this stage the task is just a draft. Its primary purpose is to 
encourage thinking in terms of non-published/published/flowscript APIs 
and start to use the above mentioned tags.

Actually I'm not convinced that creating and maintaining a special 
Cocoon doclet for Javadocs is the right thing to do.

I think it might be "nicer" to hook into Javadocs' standard doclet. But 
unfortunately this page:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/standard-doclet.html
says: "Important - These classes are part of the internal implementation 
of the standard doclet, and are subject to change without notice from 
version to version -- they are not an API. Use them at your own risk."

Taking and adjusting the source code doesn't seems desirable or allowed 
(as far as my license-untrained-eyes can see from SUN COMMUNITY SOURCE 
LICENSE Version 2.3) either.

So I decided to base the task (mostly taken from the QDoxSource 
currently) on QDox, being already part of the build and tools/lib anyway 
(but I'm open to suggestions).

WDYT?

Guido

-- 
Guido Casper
-------------------------------------------------
S&N AG, Competence Center Open Source
                     Tel.: +49-5251-1581-87
Klingenderstr. 5    mailto:gcasper@s-und-n.de
D-33100 Paderborn   http://www.s-und-n.de
-------------------------------------------------

Mime
View raw message