[Libreoffice] Script to find undocumented classes
thb at documentfoundation.org
Tue Nov 30 13:25:47 PST 2010
Lubos Lunak wrote:
> 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).
adding documentation for what you describe doesn't help much, if at
all. Core API is reasonably documented, see offapi/udkapi/sal/basegfx.
The most egregious cases of hard-to-grasp methods surely live in the
applications cores, use lots of weird abbreviations - and to
document their behaviour succinctly would prolly require as much
prose as there's code already inside them (i.e. multiple pages).
For me, a cleanly designed class with one and only one task (and a
proper mission statement, maybe - superfluous even for something
like "String"), does not need much method documentation.
Suitably-chosen method names, especially if they don't take 10
parameters, and only work for exactly 42 combinations of them, are
I simply refuse the notion that adding superficial documentation to
crappy api gets us anywhere - which does not rule out storing
hard-won knowledge of class purpose, inner workings, important pre-
or postconditions at times - and if it makes sense, as method- or
class-level doxygen documentation.
But to really fix the problem you mention, I'm afraid only
large-scale refactoring helps. And wrong documentation surely is
worse than no documentation.
(sorry for the rant, that struck a chord. Also, I'm clearly with you
that larger parts of vcl & [sv]tools public headers are in dire need
of method-level documentation. I'd even suggest to start there, that
code does not change much)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 198 bytes
Desc: not available
More information about the LibreOffice