Review of sitemap component documentation (2.1 legacy document)
Introduction
This is a coordination table to assist the systematic review of the "sitemap component documentation" which is the set of documentation available at /userdocs/ for each sitemap component (actions generators matchers readers selectors serializers transformers).
This review focusses only on this set of documentation, as part of the overall documentation review. This set is a key part, because it addresses the heart of Cocoon - the sitemap components. Having a well-defined "User Guide" will assist both users and developers to be more productive.
Please assist by sending discussion to the dev mailing list and patches of xdocs and java code via the issue tracker. See the To Do section at the bottom.
This documentation is generated as part of the Cocoon 'build docs' process. An anttask (tools/anttasks/SitemapTask) scans the java code looking for javadoc-like tags (e.g. @cocoon.sitemap.component.name) and extracts that information. For each component there is also a default document at src/documentation/xdocs/userdocs/ which contains additional manual content. The two sources are merged to form each final xdoc, with two new sections being added (Description and Info). Then Forrest builds the final set of documents as part of the normal 'build docs' process.
These are the SitemapTask attributes that are used in the code:
- @cocoon.sitemap.component.documentation - The documentation (optional)
- @cocoon.sitemap.component.name - The name of the component in the sitemap (required)
- @cocoon.sitemap.component.logger - The logger category (optional)
- @cocoon.sitemap.component.label - The label for views (optional)
- @cocoon.sitemap.component.mimetype - The mime type for serializers and readers (optional)
- @cocoon.sitemap.component.hide - If this tag is specified, the component is not added to the sitemap (optional)
- @cocoon.sitemap.component.documentation.disabled - If this tag is specified, no documentation is generated (optional)
- @cocoon.sitemap.component.configuration - Configuration (optional)
- @cocoon.sitemap.component.documentation.caching - Caching info (optional)
- @cocoon.sitemap.component.pooling.min - Pooling min (optional)
- @cocoon.sitemap.component.pooling.max - Pooling max (optional)
- @cocoon.sitemap.component.pooling.grow - Pooling grow (optional)
Coordination table
The table columns are:
- Java source - The name of the Java source file and link to javadoc.
- Document - The name of the generated document and a link to it. This is also the @cocoon.sitemap.component.name
- A - The xdoc is available to supply additional manual content.
- B - The java code is in "core" or as a "block".
- C - The javadoc-like tags (SitemapTask attributes) are available in the code.
- D - The component parameters are properly described.
- E - The code and xdoc are synchronised between Cocoon trunk and 2.1 branch.
Cell values are:
- blank - Not yet investigated.
- y - Yes.
- n - No.
- - - Not relevant.
- * - Has issues, needs more work.
There are 314 entries.
Actions
Generators
Matchers
Java source | Document | A | B | C | D | E |
---|---|---|---|---|---|---|
AbstractPreparableMatcher | n | core | n | |||
AbstractRegexpMatcher | n | core | n | |||
AbstractWildcardMatcher | n | core | n | |||
CookieMatcher | n | core | n | |||
HeaderMatcher | n | core | n | |||
LocaleMatcher | n | core | n | |||
modular/CachingRegexpMatcher | n | core | n | |||
modular/CachingWildcardMatcher | n | core | n | |||
modular/WildcardMatcher | n | core | n | |||
MountTableMatcher | n | core | n | |||
ParameterMatcher | n | core | n | |||
PreparableMatcher | n | core | n | |||
RegexpHeaderMatcher | n | core | n | |||
RegexpHostMatcher | n | core | n | |||
RegexpParameterMatcher | n | core | n | |||
RegexpRequestAttributeMatcher | n | core | n | |||
RegexpRequestParameterMatcher | n | core | n | |||
RegexpSessionAttributeMatcher | n | core | n | |||
RegexpURIMatcher | n | core | n | |||
RegexpURIDefaultsMatcher | n | scratchpad | n | |||
RequestAttributeMatcher | n | core | n | |||
RequestParameterMatcher | n | core | n | |||
SessionAttributeMatcher | n | core | n | |||
WildcardHeaderMatcher | wildcardheader | y | core | n | ||
WildcardHostMatcher | n | core | n | |||
WildcardParameterMatcher | n | core | n | |||
WildcardRequestAttributeMatcher | n | core | n | |||
WildcardRequestParameterMatcher | n | core | n | |||
WildcardSessionAttributeMatcher | n | core | n | |||
WildcardURIMatcher | wildcarduri | y | core | n |
Readers
Java source | Document | A | B | C | D | E |
---|---|---|---|---|---|---|
AbstractReader | n | core | n | |||
AxisRPCReader | axisrpc | y | axis | n | ||
ComposerReader | n | core | n | |||
DatabaseReader | database | y | databases | n | ||
DirectoryZipArchiver | directoryziparchiver | y | scratchpad | n | ||
ImageReader | image | y | core | n | ||
JSPReader | jsp | y | jsp | n | ||
ProxyReader | n | portal | n | |||
ResourceReader | resource | y | core | n | ||
ServiceableReader | n | core | n |
Selectors
Java source | Document | A | B | C | D | E |
---|---|---|---|---|---|---|
AbstractRegexpSelector | n | core | n | |||
AbstractSwitchSelector | n | core | n | |||
BrowserSelector | browser | y | core | n | ||
CookieSelector | n | core | n | |||
ComponentsSelector | n | core | n | |||
DateSelector | date | y | scratchpad | n | ||
ExceptionSelector | n | core | n | |||
GeneratorSelector | n | xsp | n | |||
HeaderSelector | n | core | n | |||
HostSelector | host | y | core | n | ||
MailCommandSelector | n | n | ||||
MediaSelector | n | session-fw | n | |||
NamedPatternsSelector | n | core | n | |||
OutputComponentSelector | n | core | n | |||
ParameterSelector | parameter | y | core | n | ||
RegexpHeaderSelector | regular-expression-header | y | core | n | ||
RegexpRequestParameterSelector | n | core | n | |||
RequestAttributeSelector | requestattribute | y | core | n | ||
RequestMethodSelector | requestmethod | y | core | n | ||
RequestParameterSelector | requestparameter | y | core | n | ||
ResourceExistsSelector | n | core | n | |||
SessionAttributeSelector | n | core | n | |||
SimpleSelector | n | core | n | |||
SitemapComponentSelector | n | core | n | |||
SwitchSelector | n | core | n | |||
XPathExceptionSelector | n | core | n |
Serializers
Java source | Document | A | B | C | D | E |
---|---|---|---|---|---|---|
AbstractSerializer | n | core | n | |||
AbstractSerializer | n | scratchpad/garbage | n | |||
AbstractTextSerializer | n | core | n | |||
ElementProcessorSerializer | n | poi | n | |||
EncodingSerializer | n | serializers | n | |||
EncodingSerializer | n | scratchpad/garbage | n | |||
FOPSerializer | n | fop | n | |||
HSSFSerializer | n | poi | n | |||
HTMLSerializer | html | y | core | y | ||
HTMLSerializer | n | serializers | n | |||
HTMLSerializer | n | scratchpad/garbage | n | |||
IncludingHTMLSerializer | n | portal | n | |||
iTextSerializer | n | itext | n | |||
LinkSerializer | link | y | core | n | ||
pcl | y | n | ||||
y | n | |||||
POIFSSerializer | n | poi | n | |||
ps | y | n | ||||
RTFSerializer | n | jfor | n | |||
Serializer | n | scratchpad/garbage | n | |||
SVGSerializer | svg | y | batik | n | ||
svgjpeg | y | n | ||||
svgpng | y | n | ||||
svgtiff | y | n | ||||
svgxml | y | n | ||||
SWFSerializer | n | swf | n | |||
TextSerializer | text | y | core | n | ||
vrml | y | n | ||||
wap | y | n | ||||
xhtml | y | n | ||||
XHTMLSerializer | n | serializers | n | |||
XHTMLSerializer | n | scratchpad/garbage | n | |||
xls | y | n | ||||
XMidiSerializer | n | midi | n | |||
XMLSerializer | xml | y | core | n | ||
sax/XMLSerializer | n | serializers | n | |||
XMLSerializer | n | serializers | n | |||
XMLSerializer | n | scratchpad/garbage | n | |||
ZipArchiveSerializer | ziparchive | y | core | n |
Transformers
To Do
Not a list of everything to be done, just a few notes ...
- Ask everyone to check the current table to see if any components were missed. Before we do anything, we need to be sure that the table is complete.
- Perhaps there are some superfluous entries.
- Create some complete entries to serve as examples and time estimates.
- Review the LinkAlarm report and fix broken links.
- Document the procedure for reviewing a document/code and for amending this table.
- Enhance the SitemapTask.java
- Add basic SitemapTask attributes to the java code for each compoent. This could be automated. Check if the SitemapTask.java copes with empty default values. Add to column C.
- Does SitemapTask scan the src/blocks/*.java ?
- Some trouble with names (e.g. EncodeURLTransformer) needs doc name lowercase (encodeurl-transformer). Perhaps need extra SitemapTask attribute or do toLower().
- Investigate docs in blocks. The "mail" block has some.
- Reduce the length of labels in the left-hand-panel of the documents, e.g. "Transformer" => "Tr" or delete the word entirely. In the generated */book.xml files.
- Develop tools to analyse the table and ensure that it remains synchronised. See the script in the repository at: tools/review-sitemap-docs/correlate-table.sh
- Monitor the email discussion on the cocoon-dev mailing list: review of sitemap component documentation
Other notes...
The "@cocoon.sitemap.component.documentation.caching" tag cannot be the last element or it will suck the rest of the javadoc description in with it.
Be careful with "@cocoon.sitemap.component.name" - it is also used for another purpose.