I think the "published-api-html" task is missing?
No, there is only a "published-api" target. It generates the html as well. However the output dirs are mostly empty as there are no "@cocoon.usage" tags, yet.
Does anyone (besides me) think the distinction between published and non-published classes/interfaces is a useful thing? IMO it's a pity that the Java language doesn't provide any means for that.
Is there a better way/format for generating docs for that?
Guido
Carsten
-----Original Message-----
From: Guido Casper [mailto:[EMAIL PROTECTED] Sent: Tuesday, May 25, 2004 3:18 PM
To: [EMAIL PROTECTED]
Subject: Javadocs for published classes/interfaces
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:[EMAIL PROTECTED] D-33100 Paderborn http://www.s-und-n.de -------------------------------------------------
