Re: Javadocs: need basic package information

[Sylvain Wallez]

David Crossley wrote:

Sylvain Wallez wrote:

Bernhard Huber wrote:

<snip/>

i think writing a single packages.xml is better than maintaing
84 package.html files.

IMO, a centralized XML file may not be better as far as keeping
it up to date is concerned :
- people may often forget to update a central file far away
from the source files.

No-one is adding package.html files next to the source
at the moment anyway. There are only 9 such files under
src/java and they are mostly over six months old.

Their age doesn't mean they're obsolete. Even more considering the large amount of information they contain ;-)

- will people really go inside a large XML file containing 89
toplevel elements to update a single package description ? I think no.

If they have the motivation to describe something, then
the type of file should not stop them. Yes, editing and
navigating a large file may become a problem.

There is one important reason for having separate
package.xml next to the component source code ... when
Cocoon is able to add new components (blocks?) automatically.

Can you elaborate more on this ? As far as I understand them (they're still fuzzy), blocks will provide some sitemap-level services implemented using block-specific libraries that won't be visible from outside the block.

How does this relate to javadoc ?

* add a packages.dtd ala faq.dtd

I don't like neither constraining the content : package.html,
as its name states, accepts any html markup. Javadoc extracts
the first sentence to build the package summary table, but the
file can contain a detailed design description of the package,
including tables, images, etc. Sure, we don't have such
detailed package.html now, but constraining the content will definitely prevent it...

<snip/>

I think that the package.xml does need to be well-structured.
This enables us to also extract information to be aggregated
into other documents, like a table of all components since
the 2.1 version.

Bernhard's proposal to use something like faq.dtd does allow
sufficient detailed description (i.e. tables, images).

Each individual package.html for javadocs consumption can be
generated from package.xml at build-time. And if a single
document of all packages is needed then that can be aggregated
from the individual docs.

Do you mean generating all package.html from a single package.xml and then aggregating back all the individual package.html in a single doc ? I don't follow you here...

Sylvain

--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }



---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]