cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: Reference Doc From Java Sources [Was Check Source]
Date Thu, 31 Jan 2002 10:30:54 GMT
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


Mime
View raw message