Thank you for trying the patch out and commenting on it.
I'm starting to think of it as a project. Here's a quick project statement.
The purpose is to generate improved Doxygen output while making maximal use of how Postgres currently does program comments.
Thinking in terms of specific steps, and adding to what you have mentioned:
- Configure Doxyfile so it produces output similar to previous output.
- Only build Doxygen output if requested
- Don't compile the filter or configure the Doxyfile if they aren't needed
- Include contrib in the sources to document
- Provide options for other (non-html) output. (Which ones?)
- Update Postgres documentation to include instructions for creating Doxygen output.
- Mention it in developer guidelines and provide sample code showing a "desired" commenting style.
Does that list seem complete? I don't want people to think we're imposing new standards or legislating new commenting styles. It's more a matter of describing what we currently do, maybe with some minor suggestions for improving.