[Libreoffice] Script to find undocumented classes

Thorsten Behrens 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).
Hi Lubos,

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
almost self-documenting.

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)


-- Thorsten
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/libreoffice/attachments/20101130/879284b9/attachment.pgp>

More information about the LibreOffice mailing list