cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Carsten Ziegeler" <cziege...@s-und-n.de>
Subject RE: Javadocs for published classes/interfaces
Date Thu, 27 May 2004 10:07:47 GMT
Guido Casper wrote: 
> 
> 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. 
Hmm, from your original mail :) (just kidding)
>>and:
>>build\cocoon-2.2.0-dev\published-api-html
>>(transformed via Ant's xslt task)


> 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.
Yes, makes sense to me. Could we add the tags to some classes,
like core interfaces etc. so that we actually *see* at least
something?

Carsten

> 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