Hi, I've spent some time going through the source code of OpenSER svn trunk lately, exposing a lot of the source code comments in Doxygen format. There's quite a number of files with documentation, but even more without, which is unfortunately not surprising in an Open Source project. You can see the latest version of the doxygen generated web site here:
http://devel.openser.org/doxygen/ I am trying to group files together in modules, you will see that if you click on "modules". Each file is given a one-line description, including a tag if it belongs to a module. Click on "File list" to see a list of all the files (and you will see how many that still lack a one-line description). If I find an interesting multiline explanation, I add that to a separate page in doxygen, you will see those if you click on "related pages". These are not edited at all and in some cases a bit strange since they are out-of-context. The important part is that we start collecting what's already in there, then add to it and edit a bit for it to make sense in this format. Having a well structured and informative source code documentation helps all. What's even more important, it lowers the barrier for entry for new developers, regardless if they want to write a complete new module, fix a huge bug or just add a small little feature. Open Source projects depend on contributions and I feel that making it easier for new members of the community to contribute is important. While the core developers are busy preparing the new release, I would ask other members of the community to assist in this effort. Go through files, add doxygen formatting (look into the existing files for some hints, or check the manual at http://www.doxygen.org). Create a patch and add it to the documentation bug tracker at the OpenSER sourceforge page (a link exists on the left hand side of http://www.openser.org ). You don't have to add information, just start with exposing what we already have in the source. Example: /* fuzzes permaglotiles heavily, return a pointer to a hermagroxy if zwobelut */ function fuzz_perma() { .... } Change this comment to /*! \brief fuzzes permaglotiles heavily, return a pointer to a hermagroxy if zwobelut */ And that comment will be the one-liner that documents this function. (The "/*!" is a marker for Doxygen to start parsing the comment). If you have multiple lines, separate the "brief" one-liner from the rest with a blank line, like /*! \brief fuzzes permaglotiles heavily * * Return a pointer to a hermagroxy if zwobelut */ To be a bit more doxygen-like, you can mark the result as a result too: /*! \brief fuzzes permaglotiles heavily * * \return a pointer to a hermagroxy if zwobelut */ See, it's not that hard! I'll be on holiday for two weeks now, so I will try to refrain from uploading a large set of patches. To keep the flow, why don't you start? Doxygenification is very easy to do with a small amount of your brain power directed towards a bad DVD on your TV. Just put the laptop in your knee, the can of Coke on the table, turn on the film and go. And if someone asks you about what you thought about the film? Just say something clever, like -"Well, I think Ingmar Bergman's deep exposure of the human side of the mantra of enlightment and depression was a bit more insightful and related to mankind of today." ...and they won't disturb you any more. Let's doxygenify OpenSER! Greetings from a sunny Sweden! /Olle _______________________________________________ Devel mailing list Devel@lists.openser.org http://lists.openser.org/cgi-bin/mailman/listinfo/devel
