apache > cocoon
 
Font size:      

Review of sitemap component documentation (2.1 legacy document)

Warning
This document was copied as is from the Cocoon 2.1 documentation, but has not yet been fully reviewed or moved to its new home.

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

Java sourceDocumentABCDE
AbstractActionncoren
AbstractComplementaryConfigurableActionncoren
AbstractConfigurableActionncoren
AbstractDatabaseActionndatabasesn
AbstractFormsActionnformsn
AbstractMultiActionncoren
AbstractValidatorActionncoren
AuthActionnauthentication-fwn
AuthActionnportal-fwn
BookmarkActionnportaln
CacheEventActionneventcachen
ClearCacheActionncoren
ClearPersistentStoreActionncoren
CommandActionnscratchpadn
ComposerActionncoren
ConfigurableComposerActionncoren
ConfigurableServiceableActionncoren
CookieCreatorActionnscratchpadn
CookieValidatorActionnscratchpadn
CopletSetDataActionnportaln
CopySourceActionncoren
DatabaseAddActionndatabasesn
DatabaseAuthenticatorActionndatabasesn
DatabaseCookieAuthenticatorActionndatabasesn
DatabaseDeleteActionndatabasesn
DatabaseSelectActionndatabasesn
DatabaseUpdateActionndatabasesn
DbXMLAuthenticatorActionnxmldbn
FacesActionnfacesn
ExpiresPipelineActionnscratchpadn
FormManagerActionnsession-fwn
FormValidatorActionncoren
HandleFormSubmitActionnformsn
HelloActionncoren
HttpCacheActionncoren
HttpHeaderActionncoren
InputModuleActionncoren
JMSPublisherActionnjmsn
LinkTranslatorMapActionnscratchpadn
LocaleActionncoren
LoggedInActionnauthentication-fwn
LoginActionnauthentication-fwn
LoginActionnportaln
LogoutActionnauthentication-fwn
LogoutActionnportaln
MailActionnmailn
MakeFormActionnformsn
modular/DatabaseActionndatabasesn
modular/DatabaseAddActionndatabasesn
modular/DatabaseDeleteActionndatabasesn
modular/DatabaseSelectActionndatabasesn
modular/DatabaseQueryActionndatabasesn
modular/DatabaseUpdateActionndatabasesn
ObjectModelActionnportaln
OraAddActionndatabasesn
OraUpdateActionndatabasesn
PropagatorActionncoren
RequestParamActionncoren
RequestParameterExistsActionncoren
ResourceExistsActionncoren
SaveActionnportaln
ScriptActionscriptybsfn
SectionCutterActionnscratchpadn
SendmailActionsendmailymailn
ServerPagesActionnxspn
ServiceableActionncoren
SessionActionsessionnsession-fwn
SessionFormActionnsession-fwn
SessionInvalidatorActionncoren
SessionIsValidActionncoren
SessionPropagatorActionncoren
SessionStateActionncoren
SessionValidatorActionncoren
SetCharacterEncodingActionncoren
TagtestActionntaglibn
modular/TestActionncore/samplesn
castor/TestBeanActionnscratchpadn

Generators

Java sourceDocumentABCDE
AbstractCopletGeneratornportaln
AbstractGeneratorncoren
AntBuildGeneratornscratchpadn
AsciiArtSVGGeneratornasciiartn
BasketContentGeneratornportaln
BasketGeneratornportaln
CalendarGeneratorcalendarycorey
ClientBindingGeneratornscratchpad/flown
ComposerGeneratorncoren
ConfigurationGeneratornauthentication-fwn
ConfigurationGeneratornportal-fwn
DirectoryGeneratordirectoryycorey
erroryn
EventCacheGeneratorneventcachen
ExceptionGeneratorncore/samplesn
extractoryn
FileGeneratorfileycorey
FormsGeneratornmailn
FragmentExtractorGeneratornbatikn
GarbageGeneratornscratchpadn
GenericProxyGeneratornproxyn
HTMLGeneratorhtmlyhtmly
HttpProxyGeneratornproxyn
ImageDirectoryGeneratorimagedirectoryycorey
IMAPGeneratornmailn
JellyGeneratornscratchpadn
JSGeneratornxspn
JSPGeneratorjspyjspn
JXTemplateGeneratorjxycorey
LinkStatusGeneratorlinkstatusycorey
LogicsheetCodeGeneratornxspn
MarkupCodeGeneratornxspn
MP3DirectoryGeneratormp3directoryycorey
NekoHTMLGeneratornhtmly
NotifyingGeneratorncoren
ParseExceptionGeneratornchaperonn
PauseGeneratorncore/testn
PhpGeneratorphpyphpn
PortalGeneratornportaln
PortalGeneratornportal-fwn
profileyn
ProfilerGeneratornprofilern
ProgramGeneratornxspn
xsp/PythonGeneratornpythonn
RequestAttributeGeneratornscratchpady
RequestGeneratorrequestycorey
RequestParameterGeneratornscratchpadn
ScriptGeneratorscriptybsfn
SearchGeneratorsearchylucenen
ServerPagesGeneratorserverpagesyxspn
ServiceableGeneratorncoren
ServletGeneratorncoren
SessionAttributeGeneratorncorey
SlopGeneratornslopn
StatusGeneratorstatusycorey
StreamGeneratorstreamycorey
SWFGeneratornswfn
TextGeneratornchaperonn
TraversableGeneratornrepositoryn
TraversableSourceDescriptionGeneratornrepositoryn
TraxGeneratornscratchpadn
VelocityGeneratorvelocityyvelocityn
wsproxyyn
WebServiceProxyGeneratornproxyn
XMidiGeneratornmidin
XMLDBGeneratorxmldbyxmldbn
XMLDBCollectionGeneratorxmldbcollectionyxmldbn
XPathDirectoryGeneratorxpathdirectoryycorey
XPathTraversableGeneratornrepositoryn
XSPGeneratornxspn

Matchers

Java sourceDocumentABCDE
AbstractPreparableMatcherncoren
AbstractRegexpMatcherncoren
AbstractWildcardMatcherncoren
CookieMatcherncoren
HeaderMatcherncoren
LocaleMatcherncoren
modular/CachingRegexpMatcherncoren
modular/CachingWildcardMatcherncoren
modular/WildcardMatcherncoren
MountTableMatcherncoren
ParameterMatcherncoren
PreparableMatcherncoren
RegexpHeaderMatcherncoren
RegexpHostMatcherncoren
RegexpParameterMatcherncoren
RegexpRequestAttributeMatcherncoren
RegexpRequestParameterMatcherncoren
RegexpSessionAttributeMatcherncoren
RegexpURIMatcherncoren
RegexpURIDefaultsMatchernscratchpadn
RequestAttributeMatcherncoren
RequestParameterMatcherncoren
SessionAttributeMatcherncoren
WildcardHeaderMatcherwildcardheaderycoren
WildcardHostMatcherncoren
WildcardParameterMatcherncoren
WildcardRequestAttributeMatcherncoren
WildcardRequestParameterMatcherncoren
WildcardSessionAttributeMatcherncoren
WildcardURIMatcherwildcarduriycoren

Readers

Java sourceDocumentABCDE
AbstractReaderncoren
AxisRPCReaderaxisrpcyaxisn
ComposerReaderncoren
DatabaseReaderdatabaseydatabasesn
DirectoryZipArchiverdirectoryziparchiveryscratchpadn
ImageReaderimageycoren
JSPReaderjspyjspn
ProxyReadernportaln
ResourceReaderresourceycoren
ServiceableReaderncoren

Selectors

Java sourceDocumentABCDE
AbstractRegexpSelectorncoren
AbstractSwitchSelectorncoren
BrowserSelectorbrowserycoren
CookieSelectorncoren
ComponentsSelectorncoren
DateSelectordateyscratchpadn
ExceptionSelectorncoren
GeneratorSelectornxspn
HeaderSelectorncoren
HostSelectorhostycoren
MailCommandSelectornmailn
MediaSelectornsession-fwn
NamedPatternsSelectorncoren
OutputComponentSelectorncoren
ParameterSelectorparameterycoren
RegexpHeaderSelectorregular-expression-headerycoren
RegexpRequestParameterSelectorncoren
RequestAttributeSelectorrequestattributeycoren
RequestMethodSelectorrequestmethodycoren
RequestParameterSelectorrequestparameterycoren
ResourceExistsSelectorncoren
SessionAttributeSelectorncoren
SimpleSelectorncoren
SitemapComponentSelectorncoren
SwitchSelectorncoren
XPathExceptionSelectorncoren

Serializers

Java sourceDocumentABCDE
AbstractSerializerncoren
AbstractSerializernscratchpad/garbagen
AbstractTextSerializerncoren
ElementProcessorSerializernpoin
EncodingSerializernserializersn
EncodingSerializernscratchpad/garbagen
FOPSerializernfopn
HSSFSerializernpoin
HTMLSerializerhtmlycorey
HTMLSerializernserializersn
HTMLSerializernscratchpad/garbagen
IncludingHTMLSerializernportaln
iTextSerializernitextn
LinkSerializerlinkycoren
pclyn
pdfyn
POIFSSerializernpoin
psyn
RTFSerializernjforn
Serializernscratchpad/garbagen
SVGSerializersvgybatikn
svgjpegyn
svgpngyn
svgtiffyn
svgxmlyn
SWFSerializernswfn
TextSerializertextycoren
vrmlyn
wapyn
xhtmlyn
XHTMLSerializernserializersn
XHTMLSerializernscratchpad/garbagen
xlsyn
XMidiSerializernmidin
XMLSerializerxmlycoren
sax/XMLSerializernserializersn
XMLSerializernserializersn
XMLSerializernscratchpad/garbagen
ZipArchiveSerializerziparchiveycoren

Transformers

Java sourceDocumentABCDE
AbstractConstrainedTransformernscratchpadn
AbstractCopletTransformernportaln
AbstractDOMTransformerncoren
AbstractExtractionTransformerncoren
AbstractSAXTransformerncoren
AbstractSessionTransformernsession-fwn
AbstractTransformerncoren
AugmentTransformeraugmentycorey
BasketTransformernportaln
BetwixtTransformernscratchpadn
CastorTransformernscratchpadn
CIncludeTransformercincludeycorey
CopletTransformernportaln
DASLTransformernwebdavn
DeliTransformerndelin
EncodeURLTransformerencodeurlycorey
ErrorAwareTraxTransformernscratchpadn
EventLinkTransformernportaln
ExtendedParserTransformernchaperonn
extractoryn
FragmentExtractorTransformernbatikn
FilterTransformerfilterycorey
FormsTemplateTransformernformsn
HTMLEventLinkTransformernportaln
HTMLRootTransformernportaln
HTMLTransformernhtmln
I18nTransformeri18nycorey
IncludeTransformerincludeyscratchpady
JPathTransformerncorey
JXTemplateTransformerjx-templatencoren
LDAPTransformerldapynamingn
LuceneIndexTransformernlucenen
LexicalTransformerlexerychaperonn
LinkTransformernportaln
LinkRewriterTransformernlinkrewritern
LogTransformerlogycorey
NewEventLinkTransformernportaln
ParserTransformerparserychaperonn
PatternTransformerpatternychaperonn
ProxyTransformernportaln
ReadDOMSessionTransformerreaddomsessionycorey
RoleFilterTransformerncorey
RSSTransformernportaln
SendMailTransformernmailn
ServiceableTransformerncoren
SessionTransformernsession-fwn
SessionPostTransformernsession-fwn
SessionPreTransformernsession-fwn
SimpleFormInstanceExtractionTransformerncorey
SimpleFormTransformerncorey
SourcePropsWritingTransformernrepositoryn
SourceWritingTransformersourcewritingycorey
SQLTransformersqlydatabasesn
TagTransformerntaglibn
TraxTransformerncoren
VariableRewriterTransformernlinkrewritern
Web3RfcTransformernweb3n
WriteDOMSessionTransformerwritedomsessionycorey
XIncludeTransformerxincludeycorey
XMLDBTransformernxmldbn
TraxTransformerxsltycorey

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.

Comments

add your comments