I’d also like to have a separate mailing list for all CVS commits. All commits should result in a mail to that maillist, wth commit’s diff file attached. So we will instantly know who to punish for not obeying teh rules.

Hey, I like documenting my own code, because i’m generally proud of the code i write! I take pride in what i do, and consider it some kind of art. My opinion is that, if you don’t like documenting your own code, it means that your code is ugly and/or you don’t like your own code.

@mblsha: It’s already underway.

@remko: I’d rather code than document, it’s that simple. I also detest doccing other people’s code, so going through Psi doesn’t appeal at all

It’s definitely a shame that Psi isn’t well commented - I’m trying to learn about C++/Qt and wish THE FORCE was with me. Perhaps this should be mentioned on the list as many people are in the process of re-writing certain parts of the codebase.

Hmm. Not sure I want to attach the actual diffs. I’m writing an email to psi-devel on the subject now.

For undernet’s ircu, we had 4 developers all pick a couple of files each and we documented (almost) every symbol in them. It didn’t take us long a couple of hours, I guess that probably reflects on IRCu being reasonably well documented to start with.

There are however some symbols that are very important to document. The major datastructures for your program are usually at the top of this list, and the functions that manipulate them. the Client, Channel and Membership structures pretty much describe most of ircu, theres lots of other bits that aren’t covered by that (Bans etc), but it’s enough for people to get the general jist of whats going on.

Pick a couple of critical functions (eg dealing with what happens when a new presence is recieved, or a new message) and document them and every function they call, it will probably take you less than an hour and you’ll cover all the important things that people that are going to hack on the code are probably going to care about.