[Libreoffice] Script to find undocumented classes
Lubos Lunak
l.lunak at suse.cz
Tue Nov 30 09:50:17 PST 2010
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 at suse.cz
More information about the LibreOffice
mailing list