Hi, > >*this* is what we need: the ability to write our documentation with the >code and the ability to factor it out and aggregate it coherently with >our own. > yep.
> > >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. 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. 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! > > >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. bye bernhard --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
