Re: [Libreoffice] Script to find undocumented classes

On Tuesday 30 of November 2010, Thorsten Behrens wrote:
> Additionally, I think most classes don't necessarily need detailed
> docs for all methods in the first place (which may also hurt later
> merging from OOo), but would already benefit from a two-line
> "mission statement" at class level (of course plus some module-level
> overview of "what's inside").

 I beg to differ. After having years of experience using a nice, intuitive and 
well-documented APIs (Qt,KDE), and being used to that, I sometimes rather 
suffer getting familiar with this codebase. Most APIs are not documented at 
all (or at most poorly, or in German, which is about the same in practice for 
many people). This is futher made worse by some APIs not being very intuitive 
(cryptic abbreviations, unclear naming, obsolete idiosyncracies, duplication, 
basic things being needlessly complicated).

 This could be a significant factor for new possible contributors. While 
patches removing dead code or similar certainly help too, the codebase can 
move forward only by people writing new code, and that requires understanding 
of the existing code.

 So I find any suggesting that docs are not necessary (or valueing merging 
higher) to be eventually shooting ourselves in the foot.

-- 
 Lubos Lunak
 l.lunak@suse.cz