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 Re: Javadocs for published classes/interfaces
Date Wed, 26 May 2004 17:50:26 GMT
Carsten Ziegeler wrote:
> 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:gcasper@s-und-n.de] 
>>Sent: Tuesday, May 25, 2004 3:18 PM
>>To: dev@cocoon.apache.org
>>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:gcasper@s-und-n.de
>>D-33100 Paderborn   http://www.s-und-n.de
>>-------------------------------------------------
>>
> 
> 
> 

Mime
View raw message