cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: Javadocs: need basic package information
Date Fri, 03 Jan 2003 03:16:46 GMT
Sylvain Wallez wrote:
> 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.

And I would personally be *very* irritated by any other view on this 
subject. I mean: once the code is into our CVS is not yours anymore its 
*ours*. It's "cocoon community"'s which means that there will not be 
*areas* where others are not allowed to work or should feel 
uncomfortable in entering and changing.

Nobody with commit access (no matter *why* or *how* he/she got commit 
access) should be scared/uncomfortable about modifying *any* part of 
CVS. In fact, that's exactly why we have CVS in the first place: so that 
people know that rollback is always possible and they don't feel afraid 
of modifying stuff.

I'm very serious: any behavior that will even slightly suggest feelings 
of code ownership from a committer will be considered *very* seriouly as 
an obstacle to the evoulution of this project and *won't* be tollerated.

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

I hear you. I hear you. This year things will change, believe me.

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

I think that javadocs (and docs, in general) should have a little 
skeleton provided by who actually wrote the code and later 
edited/modified/extended by others.... this is because sometimes the 
original author might take too many things for granted.

But I want to stress one point: the barrier for document writing is 
high, too high, this year I'm going to make a serious effort to lower 
that barrier.

-- 
Stefano Mazzocchi                               <stefano@apache.org>
--------------------------------------------------------------------



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


Mime
View raw message