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. <[EMAIL PROTECTED]> Friedrich Nietzsche -------------------------------------------------------------------- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
