Return-Path: 
 <cocoon-dev-return-21978-apmail-xml-cocoon-dev-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-cocoon-dev-archive@xml.apache.org
Received: (qmail 16123 invoked by uid 500); 31 Jan 2002 10:30:37 -0000
Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:cocoon-dev-help@xml.apache.org>
list-unsubscribe: <mailto:cocoon-dev-unsubscribe@xml.apache.org>
list-post: <mailto:cocoon-dev@xml.apache.org>
Reply-To: cocoon-dev@xml.apache.org
Delivered-To: mailing list cocoon-dev@xml.apache.org
Received: (qmail 16112 invoked from network); 31 Jan 2002 10:30:37 -0000
Message-ID: <3C591CDE.9DB44557@apache.org>
Date: Thu, 31 Jan 2002 11:30:54 +0100
From: Stefano Mazzocchi <stefano@apache.org>
X-Mailer: Mozilla 4.79 [en] (Windows NT 5.0; U)
X-Accept-Language: en
MIME-Version: 1.0
To: cocoon-dev@xml.apache.org
Subject: Re: Reference Doc From Java Sources [Was Check Source]
References: 
 <CCD084B0E779D411A70300508B6622260361FA78@exchukahis02.experian.co.uk>
	 <02012821234600.01975@igacer> <3C55A45A.90703@a1.net>
	 <02012912011602.01975@igacer> <3C55FBA6.3000401@a1.net>
	 <3C56E266.13B3D1EB@apache.org> <3C572957.7070806@a1.net>
	 <3C57C2AD.900C3C8F@apache.org> <3C5885F3.70900@a1.net>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

Bernhard Huber wrote:

> >But the fact that we use javadocs syntax and javadoc tools might be
> >wrong!
> >
> >Now, I see two possible syntaxes:
> >
> >1) turn javadoc tag into namespaced ones (might becoming a black art)
> >
> >
> >2) write our own 'special-comment' with nested XML documentation
> >
> > /*?
> >     <doc:doc xmlns:doc='...'>
> >      ...
> >     </doc>
> > ?*/
> >
> No I don't like 2), this will make it impossible to use the doclet API!
> Doclet API won't give you access to that comments, AFAIK.

Good point.

> What about, putting the complete XML to a single javadoc tag, like this:
> 
> /** My one sentence description
>  * @namespace:cocoon http://apache.org/cocoon/2.0/
>  * @cocoon:doc <doc:doc xmlns:doc='...'>
>  * <doc:head>bla, bla</doc:head>
>  * <doc:body>bla, bla</doc:body>
>  * </doc:doc>
>  */
> 
> I think it's not funny writing xml documentation in the java comment.
> If the number of javadoc tags is small, and clear, I think it is better
> than writing xml in the comment.

Completely agreed.

> Writing xml in the comment could be painful for programmers, and might
> be simply ignored by lazy programmers.
> Keep in mind that programmers/developers are supposed to write the
> documentation!

Absolutely. Javadocs are a pain by itself, we should make it as simple
as possible to add features to this system.
 
> >
> >
> >Another choice is the tool:
> >
> >1) write a tool on our own
> >
> >2) write a doclet
> >
> >The second option is nicer if the output is completely XML-ized!
> >
> > <javadoc:class xmlns:javadoc="....">
> >     <doc:doc xmlns:doc='...'>
> >      ...
> >     </doc>
> >   <javadoc:method ..../>
> >   <javadoc:variable ../>
> > </javadoc>
> >and so on.
> >
> >*this* would be incredibly cool, since it would give us the ability to
> >'refactor' and aggregate code documentation easily from an XML-based
> >publishing framework.
> >
> >
> >
> >So, using Velocity is cool, but it's somewhat limited (unless you want
> >to write a java parser in Velocity :) javadoc already comes with a java
> >parser... but I never wrote a doclet so I'm not sure how that goes (but
> >we already have a javadoc DTD that suits our needs!)
> >
> Note: The sample code I wrote is a doclet, I used Velocity only for
> generating the xml documents.
> Using Velocity was driven by:
> * Be flexible in generating what kind of xml document
> * Be flexible in accessing object provided by the doclet API.
> 
> Thus the Velocity templates are generators.
> Thus the Velocity templates are transformers.
> 
> There is no need to implement a java parser in Velocity.
> 
> Short note about doclet: You have an API, providing you with beans about
> all parsed classes, packages, methods, members.
> Thus you can access the full name of a class like: 'classDoc.fullName()'.
> 
> Thus my suggestion:
> 1) Programmers keep writing java source documentation.
> 2) Programmers do not write xml, but javadoc tags.
> 3) A project may define special tags, and a namespace
> 
> 4) A doclet generates xml documents from the java documentation.
> 5) Using the default doclet of javadoc still provides valid, and
> sensefull html documentation.
> 
> 6) Using VelocityDoclet you have to write templates which generates xml
> documents.
> 7) You may want write several "families" of templates/doclets to
> generate different xml documents from the java sources.
>  So you can generate xml documents having same info as today
> html-javadocumentation, ignoring project specific tags.
>  You can generate xml documents taking only some classes into account,
> and some project specific tags for having project specific reference
> documentation, ignoring method details.

Totally +1

I'm going to spend some time taking a good look at your doclet today and
to the other doclet implementations available.

Catcha l8r.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org