Hi All,

There's a very very rough class map for MediaWiki's includes/ directory located at: http://files.nickj.org/MediaWiki/mediawiki-includes-rough-class-map.png

It's very much a work in progress, but the reason for this email is to ask for help with any class descriptions.

Classes in green have a description in their comments, so they are happy; classes in yellow do not have a description, so they are sad. Roughly 30 to 40% of classes do not have descriptions. You can help turn a sad yellow class into a happy green class, by giving it a description all of its own.

Basically, if you see a class in yellow, and you go "hey, I know what that is", or by looking at the code you work out what it is, can you please either add the description to the class and check it into subversion, or alternatively can you please email me any descriptions, and I'll add them?

I'm only looking for one or two or three sentences that give a very brief overview of what the class does, or what its purpose is. If you want to write more, that's fantastic and certainly welcome, but for the purposes of this exercise, a short top-level description is all that's being asked.

Something else that would probably help is if people can maybe include an "@addtogroup" tag in the class comments, to indicate the general conceptual group that class belong to. The current @addtogroup tags used in includes/ are: @addtogroup Cache @addtogroup DifferenceEngine @addtogroup Language @addtogroup Metadata @addtogroup Parser @addtogroup Search @addtogroup Skins @addtogroup SpecialPage @addtogroup Spyc @addtogroup Templates @addtogroup UtfNormal

There should probably be some extra ones, including at least: @addtogroup Api @addtogroup Database (feel free to call out or create any extra ones that you think are missing)

Also, it may be for some classes that they already have descriptions, but they're not in a format or a location that a documentation system can pick up. The format that should always work is like this: ------------------------------------------- /** * This is a short description of the class. Anything here will appear * inside the box, including this second sentence and this * stuff on the third line. * * This is a more detailed description. It is optional, and will NOT * appear inside the brief description box. It is separated from the brief description * by a blank line. Some examples of stuff that might go here include design ideas, * usage examples, thoughts for improving efficiency, technical notes, future plans, * and so forth. * * @addtogroup SpecialPage */ class someClass { // ... implementation ... } -------------------------------------------

(i.e. use Javadoc comments, right above the class declaration; any extra tags like "@author", "@see", "@todo", etc, are fine too).

If we can get a few more class descriptions in, then I'll do another run, and this time try and arrange them according to their "@addtogroup" tag (so that SpecialPage classes are grouped together, Api classes are grouped together, Parser-related classes are grouped together, Database classes are grouped together, etc).

That should get the number of lines crossing over other things down, and should group conceptually related files together.

As per before, any resulting diagrams will be under a free license (e.g. GFDL + GPL), and uploaded to commons.

-- All the best, Nick.