cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira ...@upaya.co.uk>
Subject Re: [Proposal] review of sitemap component documentation
Date Tue, 30 Nov 2004 20:57:53 GMT
David Crossley wrote:

> The current User Guide documentation has one document
> for each Sitemap Component, e.g.
> http://cocoon.apache.org/2.1/userdocs/generators/file-generator.html
>
> Each main document has a shell with some content
> in src/documentation/xdocs/userdocs/*
>
> During the 'build docs' a "SitemapTask' is called.
> This scans the java code and extracts certain javadoc-like
> tags and appends this information to the top of each
> shell document to produce the "Description" and "Info"
> sections.
>
> We need to consistently review both the shell documents
> and the javadoc-like tags in the code. While we are
> in there, the actual javadoc comments and tags could
> also be reviewed.
>
> I propose to create a planning document to co-ordinate
> this effort. It would be a table which lists each sitemap
> component and whether each aspect has been reviewed.
> The columns are not yet determined, but they would
> be things like: shell doc present, shell doc suitable,
> javadoc tags present, javadoc tags suitable, etc.
>
> Then i, and others, can gradually work through the list
> and get each document/tags up-to-date. If we cannot
> readily determine the info, then we would ask pertinent
> questions on the dev list. If that doesn't help then
> we can dig in the 'svn log' to find the culprits.
>
> This is something that i have been wanting to do for
> ages and with the recent brouhaha about documentation,
> i thought it finally time to get started. It is going
> to be a long road.
>
> If no-one says stop, then i will just commence soon.

Have any docs actually been done with this process? I'm curious to find 
out more about how what the conversion actually does. (I guess I could 
just try it, but then, that would be too easy!)

Regards, Upayavira


Mime
View raw message