Bernhard Huber wrote: > > Hi, > > > > >What about coming out with a more-or-less standard extention to the > >javadoc system and provide namespaces? for example: > > > > /** > > * This is my comment. > > * > > * @namespace:cocoon http://apache.org/cocoon/2.0/ > > * @cocoon:deprecated no > > * @namespace:xsp http://apache.org/xsp/1.0/ > > * @xsp:deprecated yes > > */ > > > >what do you think? might be FS but I think tag collisions will happen > >frequently expecially if this system is moved to Ant or something like > >that. > > > I have already forgotten abbrev FS.
Flexibility Syndrome. > BTW, I think your suggestion makes a > lot sense, and it's quite flexible. exactly :) my question was: 'too much'? > We may even predefine some namespaces, like > @namespace:cocoon http://apache.org/cocoon/2.0/. yes, as long as you leave the ability to be 'overruled' in the source file. > For the xsp I see no usage, but maybe I'm missing something. Well, don't know, maybe it could be useful for automatic Taglib documentation, to map methods and parameters to the taglib markup. > For the non-sitemap-and-avalon-components-only let's introduce > @namespace:avalon http://apache.org/avalon/4.1/ ? Great. > > > >>More cocoon:tags: > >>@cocoon:optional [yes|no] describing if it is optional > >>@cocoon:core [yes|no] describing if its core > >> > > > >If something is not core is optional, or is there something in between? > > > Yup: default, What's about, using "status", we may even add deprecated,... > @cocoon:status [default|core|optional] +1 > > > > > >>@cocoon:input-dtd for transformers describe the expected input > >>xml-document-type > >>@cocoon:output-dtd for transformers, and generators describe the > >>expected xml-document-type produced. > >> > > > >Nah, this doesn't work. > > > >XSLTTransformer: what are the input/output schemas? > >XMLSerializers: what is the input schema? > > > >yes, some components know the output or the input (directory markup for > >the directory generator, FO for PDFSerializer), but is this worth the > >effort? pipelines can't be validated at authoring time anyway. > > > Yes, but imagine you want to use the directory generator, you must know > the DTD of the xml generated, > if you want to write the XSLT. > I understand the concern, but using the generator you must know the DTD, > so somewhere it should be documented anyway. Thus I suggested these > javadoc tags. On the other hand it's only reference documentation. Good point. But let's make this DTD agnostic since in the future nobody will use DTDs anymore: what about something like @cocoon:input-schema @cocoon:output-schema ? > >>@cocoon:objectModel ? describe what is put into the objectmodel map. > >> > > > >Hmmm, I think this is too code-level. > > > >What about things like in-out parameters [for actions, matchers, > >selectors], or things like returned tokens... anything that can be > >useful for sitemap authoring (probably even to assist an authoring tool) > > > Yes, that's a point. > For example a try for a I18NTransformer documentation: > > /** > * Internationalisation transformer; used to transform i18n markup into > text based on a particular locale. > * > > * @namespace:cocoon http://apache.org/cocoon/2.0/ > > * @cocoon:name="i18n" > * @cocoon:status="core" > * @cocoon:config element-name="catalogue-name" > * type="string" > * description="base name of the message catalogue (<i>mandatory</i>)." > * @cocoon:config element-name="catalog-location" > * type="context-location" > * description="location of the message catalogues (<i>mandatory</i>). > * @cocoon:config element-name="untranslated-text" > * type="string" > * description="default text used for untranslated keys (default is > 'untranslated-text'). > * @cocoon:config element-name="cache-at-startup" > * type="true|false" > * description="flag whether to cache messages at startup (false by > default). > > * @cocoon:action http-request-parameter name="lang" > description="defines the locale in the http request parameter" > * type="{language}(_{country}(_{variant})?)?" > * @cocoon:action http-session-parameter name="lang" > * > */ Uh, getting kinda verbose... > Moreover what about the xconf parameters? > For example XSLT processor allows the configuration parameters: > use-store, incremental-processing > Lets'define: > @avalon:param name="incremental-processing" > allowed-values="true|false" > description="Turn 'incremental-processing' to true if you want a > continous output" yes, makes sense. > Probably I have to reread the doclet documentation, there is some > special tag procesing for Param tags, > other wise we define to much tags, and it will become an art of its own > writing that kind of documentation.... > > Structurally I see some problems describing hierachical configuration > this kind of flat javadoc tags. I was thinking the same thing. Even more: javadocs are very granular since they describe methods classes and variables.... we just need to describe classes and we need more nesting capabilities. Are we sure javadocs is the tool we need for this? > But perhaps we may check, if some mandatory tags are missing in the > javadoc, and generate warnings. > > Implementation note: > I think using Velocity is okay for that task, I read a note in the > velocity mailing list, that someone used this kind of approach > for generating EJB home, and interface java sources. > The XDoclet may be more flexible, but I didn't managed to understand the > structure.... The cool concept about javadocs is that they live with the code, but allow documentation to be factored out (un-cross-cutted, for the AOP oriented of you) (yes, I see documentation as an 'aspect' of the source code) *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. 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> ?*/ 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!) -- 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]
