Re: [Libreoffice] Script to find undocumented classes

On Tuesday 30 of November 2010, Thorsten Behrens wrote:
> 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.

 What is core API then? Do things under e.g. libs-core count as well? If yes, 
then just have a look there.

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

 ??? Documentation is not about stating again what can be read from the code, 
it is about summarizing and explaining it. A short description of a function 
can save the time reading it all (especially if non-trivial) or help finding 
the needed function, a description of strange code saves the time of figuring 
out why and what it does exactly. Nobody is talking about "int foo = 10; // 
assign 10 to foo". And if a function really needed multiple page of comments 
to explain it, then still I'd rather have that then spend a day (or even 
more, if it really required that much description) figuring it out the moment 
I need to touch it.

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

 Too bad LibO seems to be huge enough to contain many of those that do not fit 
this.

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

 I have no idea why you think I'm talking about superficial documentation.

 Besides, it's a question of what is superficial. If you think String is 
trivial, what does str.GetTokenCount('.') give you if str is "a.a." ? I spent 
several minutes on this and would have rather appreciated a one-liner saying 
what the function actually does.

> But to really fix the problem you mention, I'm afraid only
> large-scale refactoring helps.

 Quite possibly. But a) that's a lot more work, b) for that, it still helps to 
know what the code is supposed to do in the first place.

> And wrong documentation surely is worse than no documentation.

 No idea why you think I'm talking about this either.

-- 
 Lubos Lunak
 l.lunak@suse.cz