cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernhard Huber <berni_hu...@a1.net>
Subject Re: Javadocs: need basic package information
Date Wed, 25 Dec 2002 09:05:00 GMT
hi,
>> 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.
> - will people really go inside a large XML file containing 89 toplevel 
> elements to update a single package description ? I think no.

hmmm, i'd like to disagree.
somehow it comes down to question who will most likely write the
package docs.
Programmers? than package.html is better
NonProgrammers, or NotOriginalProgrammers than package.xml is better.
But I see your point of view.

>> * 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...
hmmm, as of today there is nearly no package.html at all.
using a single package.xml my identation is to make
this kind of documentation available for the cocoon documentation.
using a single package.xml helps to achieve this, as far as i see.

moreover i think that in most case programmers tend to
write only some class javadoc, and a second person having a bit
more distance will write the additional docs -- i know it from
my own experiences claiming to add javadoc documentation, don't
doing it, and adding it to foreign code missing it. :-)

> 
> My .02 euro...
okay

regards bernhard


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message