And so it begins...

[David Shrewsbury]

Hello fellow Doxygenators,

In case you haven't heard, the Community Doxygen Project is
beginning to take shape. I'm trying to get the last few details
together as to how the process will work. So far, the server
developers have suggested the following approach:

- work only on the "sql" subdirectory,
- begin from a latest 5.0 clone,
- run/improve/rerun Mats' conversion tool
- once automatic conversion is done, manually fix the rest
- ask server developers to add comment contents where really
   missing (such as module comments)
- generate Doxygen docs for the "sql" files
- get the result reviewed by the developers (here we do some work)
- merge into latest 5.0
- once happy, merge to 5.1, 5.2
- repeat the same for the remaining 5.1-only comments,
- repeat the same for the remaining 5.2-only comments.

The conversion program that Mats Kindahl wrote was a flex
program. I tested it out and decided that a Perl program could
handle things a little bit better, so I wrote a Perl version that
should work ok. It's not perfect, so there will still be some manual
intervention involved with the target comments.

After some discussion with Jay and Timour Katchaounov, I believe
we should follow this approach that mirrors the one outlined above:

1) Each team member will work on a set of files in the "sql" directory
2) Run the Perl conversion script on the file(s) you are working on
3) Fix the comments changed by the conversion script
4) Add comments to functions where they are missing and where
you can understand the code to do so.
5) Ask MySQL server developers to add comments to functions
where we need help (i.e., the hard stuff)
6) After the file(s) are complete, get approval from the server
developers.
7) Submit completed files to me. I'll batch them up and send them
to Jay so that he can commit them to the source tree.

How #5 and #6 are going to work is still a bit fuzzy. It has been
suggested that we could use the MySQL Bug Reporting system
to do this, but someone at MySQL will have to add a new bug
category before we can do that. We might be able to do #6 by
building the doxygen html files, publishing them, and let all of
our changes get approved at once, rather than one file at a time.
Until these details are worked out, I think we can begin doing
steps 1-4. I'll keep you informed about how we'll do #5 and #6.

I'm not sure of the best way to divide up the work (step #1).
Timour suggested that we might want to distribute the work
based on "units" of functionality. A "unit" may be one file, or
it might spread across many files. I would agree with this, but
I'm not sure that we have the knowledge within the group to
identify these "units".  :-)  I think we should each just pick a
file (or set of files) to work on, and if you see that someone
else has taken a file that logically belongs with one that
you are working on, just ask them to let you work on it.

In order to avoid duplication of work, just send an email to the
list with a few of the files you want to work on and we'll
consider those checked out. Don't check out too many at once
just in case you get real busy with your day job.  :-)  I'll try to
maintain a list of which files are available, which ones are
checked out, and which ones are complete. I'll put the list on
my website as a link off of http://www.shrews.us/doxygen. 
Hmm... maybe I can find some time to write a file checkout
system using the MySQL database on my host...

Some other thoughts:
  * Use only the tags found on the project wiki page
(http://forge.mysql.com/wiki/CommunityDoxygenProject).

  * Use the source from the latest 5.0 version (now it's 5.0.27).
Don't use the Bitkeeper sources. Use the source tarball that is
available from the MySQL download section.

  * I put my doxygen config file for the 5.0.26 tree up on my
website. It parses only the contents of the "sql" directory. Feel
free to use it if you wish. I'll be modifying it for the 5.0.27 branch
soon.

  * Leave sql/mysqld.cc for me. I want to use it to generate the
main page of the doxygen HTML documentation.

-Dave