Hi Lubos, you wrote:
I'm not asking for anything ridiculous like having a paragraph explaining every line, I'm saying that everything non-trivial should have at least some documentation
Good, then we're mostly on the same page. Then we're both talking about mission statements, higher-level interrelations etc.
You know, if, after figuring out all these things about QuickFormatDoc(bool) and, you at least wrote down "the bool argument probably means that <whatever> but it has a lot of side-effects", you would very likely still have helped Sebastian a lot.
Well, I guess that's the point of contention we have here. A comment like that is useless in my book. And I somehow wanted to preemptively counter the notion that, like a cargo-cult, putting documentation on LibO code will magically make it intuitively usable - just because KDE is intuitively programmable, and has documentation. But I guess this topic is now thoroughly discussed to death, I hope my point, and my preference, is clear. We'd all love to have more documentation inside LibO, but neither me, nor anybody else I believe, will start mandating certain ways of documenting. We welcome cleanups, fixes and features - and if that comes with helpful header documentation, extra brownie points. ;) So just in case, let's agree to disagree & keep the patches coming! :) Cheers, -- Thorsten
Attachment:
pgpNKFyUuHpYQ.pgp
Description: PGP signature