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) Cheers, -- Thorsten
pgpxbxY0c6BKk.pgp
Description: PGP signature
_______________________________________________ LibreOffice mailing list LibreOffice@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/libreoffice
