Doxygen

Blowtorch on full powerHere’s a really easy way of getting involved with Metacity which doesn’t even involve being able to compile it, can be carried out even if you only have a basic knowledge of C, and will teach you something about the way the system works and get you credit in the release notes.

A goal of mine for 2.26 is to see all the functions documented. I’d like to see every function begin with a comment saying what it does, what its parameters are, and what its return value is. And you can figure this out by reading the code– or if you can’t, you can read more of the code to find out, or come here and ask. And really, if you can’t figure it out, that’s nothing to be ashamed of– it shows we really needed the comment.

In my opinion, the system used by Doxygen, which is similar to that used by Javadoc, does everything we need in a reasonable way, and for a few months I have been adding documentation comments to functions all over the place– I think bell.c is a good example of the style, though I’ve learned a few new things about the Doxygen system since then that I’d like to modify. You can see some of the results here. However, there’s a lot left to do, and I could probably be spending my Metacity time better by fixing bugs, since I know the system pretty well by now, and this is something that can largely be done by people who are learning it (given that they’re supplying patches which will be checked for quality by someone who knows what they’re doing).

If you want to help work on this, sort out here which module you’d like to help work on, so we don’t have two people working on the same place. If you don’t know, I can suggest something. I’ll make a bug sometime so patches can be attached. It’s far more important that nonstatic functions are documented than static ones. Oh, and don’t forget to start block comments with a slash followed by two stars.

Photo credit: Terence T.S. Tam, cc-by-nc-sa.