How to contribute?
Code
TBD
General documentation
These instructions only work if you have an active account in our Daisy CMS and got the doc editor role assigned. If you haven't, create your account at http://cocoon.zones.apache.org/daisy/registration and ask at dev[_at_]cocoon.apache.org for editing rights.
Editing a document
Simply follow the "Edit" link at the bottom of a page, login in and select Page Actions - Edit from the menu.
Adding a document
Go to http://cocoon.zones.apache.org/daisy/, login and select the
documentation site where you want to add your new document. Select New
Document from the menu. The recommended document type is Cocoon
document.
If you want to make your new document appear in a navigation menu, click on
Go to navigation document below the navigation menu and select
Page Actions - Edit.
Sitemap component documentation
For documenting sitemap components, we use a system whereby certain parts of the documentation are extracted automatically from the Java sources using a tool called sitemaptags2daisy.
If you are not a committer, make sure that you have checked out the latest version of the Java source file from SVN, make your changes and create a patch file. Create a new patch issue in JIRA and add your diff file.
Editing the documentation of a sitemap component
Only edit the content of the the Long Description part in Daisy. The short description and the value of the fields are automatically assigned from the Java sources, so if you change them in Daisy, these changes will get overwritten the next time the sitemaptags2daisy tool is run.
Adding documentation for a new sitemap component
If running the sitemaptags2daisy tool is not an option (no time, no privileges, ...) then create manually a document of type "Sitemap Component". In the JavaClass field, enter the fully qualified name of the implementation class. Leave the other fields and the Short Description part empty, they will be assigned the next time the sitemaptags2daisy tool runs. Enter the documentation in the Long Description part.
Adding javadoc tags
The following special javadoc tags are supported (none of these are strictly required by the sitemaptags2daisy tool):
- @cocoon.sitemap.component.name
default name with which this component is declared in the sitemap - @cocoon.sitemap.component.documentation.disabled
excludes the component from the documentation - @cocoon.sitemap.component.documentation
A short (one-paragraph) description of the component. Can contain HTML markup (preferably only inline tags). - @cocoon.sitemap.component.documentation.caching
A comment about the caching of this component. The cacheability of the component is figured out automatially by its implemented interfaces, but this tag allows to provide a short comment on the chaching conditions. This is mapped to a field in Daisy, thus should not contain HTML markup.