Having the code as compatible as possible with multiple open-source documentation-generation systems is surely a good thing. To that end, I wasn't trying to reduce Doxygen compatibility, I was trying to improve phpDoc compatibility. These two goals are NOT incompatible. In their most-commonly-used functionality, there is a lot of overlap between the systems. Things that cause one system to squeal will often not make sense to the other system either. To that end, most of the changes help _both_ Doxygen and phpDoc. I guess I should have explained this in the commit message, so as to avoid being reverted, huh? ;-) Well, let me try and correct that now. Specifically, to run through the changes: Helps both. Doxygen does not seem to support @url, but it does support @link. [Ref: http://www.stack.nl/~dimitri/doxygen/commands.html#cmdlink ] Helps both. Doxygen does not seem to support @fixme, but it does support @todo. [Ref: http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodo ] Helps both. Doxygen wants <i> tags be closed with </i> too. [Ref: http://www.stack.nl/~dimitri/doxygen/htmlcmds.html ] Doxygen supports both, whereas phpDoc only supports @todo. However, having outdated documentation helps nobody, and most of the @bug items were fixed over 18 months ago, so there is no point including them as unresolved bugs in doxygen's autogenerated documentation. There was one instance where an open bug was merged into an existing @todo that described the same thing, namely this: If there is any objection to this, then I apologize, and it can be left as-is. Helps both. Doxygen does not seem to support @obsolete, but it does support @deprecated. [Ref: http://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecated ] On further inspection, I _think_ that what was intended was "/**@{*/" to mark the start of a grouping: http://www.stack.nl/~dimitri/doxygen/grouping.html (i.e. one brace only). However, removing this does NOT help Doxygen, and I regret doing this, and think this should NOT have been removed in Article.php, LinksUpdate.php, and UserMailer.php. For Database.php, it's a little unclear why the grouping is there, but I'm happy to leave it as-is. Doxygen does not seem to support @access (Ref: http://www.stack.nl/~dimitri/doxygen/commands.html ) However, I was not adding these tags (i.e. this phpDoc-specific syntax was already in the code base), rather I was simply ensuring it was either "private" or "public". This, therefore, is neutral to Doxygen. Helps both. @desc does not seem to be supported by either Doxygen, or PHPDocumentor. Doxygen does not seem to support either @licence or @license (Ref: http://www.stack.nl/~dimitri/doxygen/commands.html ) However, I was not adding this tag, I was changing from one to the other. This, therefore, is neutral to Doxygen. */") The javadoc comment style is supported by Doxygen [Ref: http://www.stack.nl/~dimitri/doxygen/docblocks.html ] Either helps both, or is neutral to doxygen. For deleting blank lines between classes and their descriptions, either helps both, or is neutral to doxygen. For moving descriptions from file headers to above the classes they are describing, I suspect this helps both. Helps both. No matter what documentation system you use, you would benefit from a one-sentence description of what a class does, and why it exists. I hope that the above allays any fears that people may have that I was somehow trying to muck up the docs, or make them incompatible with Doxygen. If other folks want to use Doxygen, then I have no problem with that. In short, with the exception of the grouping (which I fully admit I was wrong about), whether you use Doxygen, _OR_ you use PHPDocumentor, you are either the same or better off to have this commit in the code base. All the best, Nick.