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. BTW, I think your suggestion makes a lot sense, and it's quite flexible. We may even predefine some namespaces, like @namespace:cocoon http://apache.org/cocoon/2.0/.
For the xsp I see no usage, but maybe I'm missing something. For the non-sitemap-and-avalon-components-only let's introduce @namespace:avalon http://apache.org/avalon/4.1/ ? > >>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] > > >>@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. >>@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" * */ 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" 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. 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.... bye bernhard --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
