> Reference Guides > - Guide for all built-in pipeline components with descriptions of > parameters (I know this exists, but it's incomplete. I know some of > this info is in the API, but it's inefficient for users to find.) > - Guide for all built-in logicsheet tags (just tags and their meaning, > not introductory material)
I'd like to suggest introducing some special javadoc tags helping to generate reference documentation automatically. This approache is like xdoclet, and vdoclet projects on sourceforge. You may see a rough example at http://members.a1.net/berni_huber/developers/index.html . I once posted suggestions about these tags. The big advantage would be reference documentation is always uptodate. The big disadvantage is the developer has to write more javadoc documentation, and the already existing java sources must be changed. There was already some mails regarding this approach, see "doclet" in the mail-archives. A quick summary: i see two possibilities to enhance the docu see also ( http://marc.theaimsgroup.com/?t=101226845700001&r=1&w=2 ) 1. include some external xml-snippet, but this way docu and java source will go separate ways more easily as today 2. enhance the java source code with some specific java doc tags A first try was SearchGenerator.java defining "@cocoon:name search". Let's introduce for every behaviourale apect of an sitemap component. As I'm not a sitemap component guru so i'm quite sure i miss some aspects. The Players: Action Generator Selector Matcher Transformer Serializer Readers The Tags General javadoc-tags @cocoon:name {name} the default sitemap name of the sitemap component, eg @cocoon:name i18n, @cocoon:name xslt @cocoon:status [default|core|optional|scratchpad] status of the sitemap component, for TraxTransformer @cocoon:status default, for I18N Transformer @cocoon:status core From the Avalon-Context Javadoc-tags For Sitemap Components being Configurable @cocoon:config element="{name}" [parent="{name}"] type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}] e.g.: For I18N Transformer @cocoon:config element="catalogue-name" parent="none" type="string" description="basename of the message catalog" required="yes", Javadoc-tags For Sitemap Components being Parameterizable @cocoon:parameter name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}] Javadoc-tags For Sitemap Components using Context @cocoon:context name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}] From the Servlet-Context Javadoc-tags For Sitemap Components using http request-parameter @cocoon:http-request parameter name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}"] for SearchGenerator: @cocoon:config element="analyzer" type="FQN" description="This element defines the analyzer to use for searching. Take care to use a compatible analyzer as used when generating the index. " required="no" default="org.apache.lucene.analysis.standard.StandardAnalyzer" Javadoc-tags For Sitemap Components using http request-attributes @cocoon:http-request-attribute name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}"] Javadoc-tags For Sitemap Components using http session attributes @cocoon:http-session-attribute name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}"] From the Sitemap-Context Javadoc-tags For Sitemap Components using Sitemap Parameters I think its quite a major task to realize that kind of docu, on the other hand cacheability can be deduced from the the class descriptor directly if checking for Cacheable interface. Moreover if the tags are defined while generating the reference docu we might check if Contextualize is implemented that there are @cococoon:context tags missing and vice a versa. > >> ----------- >> 8. How can we make it easier/more inviting for people to participate >> in the document development process? What kinds of architectural >> mechanisms can we implement to support document >> development/refinement, given the current hosting environment of >> Cocoon's web site? > What about jguru? Adding a cocoon forum at jguru? bye bernhard --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
