cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylvain.wal...@anyware-tech.com>
Subject Re: Javadocs: need basic package information
Date Wed, 01 Jan 2003 21:07:19 GMT
Bernhard Huber wrote:

> 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.


This raises an interesting point : you seem to imply that the Cocoon CVS 
is divided in areas that belong to particular individuals or group of 
individuals, and that "strangers" to an area cannot modify what's in it.

Introducing such distinctions can be IMO very damageable to the dynamics 
of group development. NonProgrammers have the absolute right to document 
what's in the "src/java" directory, and they even should be encouraged 
to do it since everybody knows that programmers are often not good or 
lazy at writing docs.

This is my particular case, and I personally have absolutely no problem 
if someone adds some javadoc or package.html to some code that I've written.

>>> * 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. 


Something I dislike and makes me reluctant to write docs is having to 
write them in XML format (be it xdoc or something else). With 
package.html, I can just start Mozilla composer and start writing using 
a wordprocessor-like GUI.

> 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. :-) 


I have a similar experience. One is supposed to understand the code he 
writes (if not then there's a real problem ;-), and that's why we often 
don't document enough our own code. When reading poorly documented 
foreign code, one makes an effort to understand that code, and then 
documenting it is a way to share this effort and avoid it to others.

But this should occur in the same source files, that we are all, 
Programmers and NonProgrammers, responsible for.

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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message