On 3/28/07, nickj(a)svn.wikimedia.org
<nickj(a)svn.wikimedia.org> wrote:
Log Message:
-----------
PHPDocumentor [
http://en.wikipedia.org/wiki/PhpDocumentor] documentation tweaking stuff.
My impression is that we're officially using Doxygen, not phpDoc.
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:
* @url becomes @link
Helps both. Doxygen does not seem to support @url, but it does support @link.
[Ref:
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdlink ]
* @fixme becomes @todo
Helps both. Doxygen does not seem to support @fixme, but it does support @todo.
[Ref:
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodo ]
* HTML tags in descriptions must be closed / balanced.
Helps both. Doxygen wants <i> tags be closed with </i> too.
[Ref:
http://www.stack.nl/~dimitri/doxygen/htmlcmds.html ]
* @bug was removed (where the bug was long fixed), or
changed into a @todo
(in the few situations where the bug was still pending)
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:
- * @todo Check for RFC 2822 compilance
- * @bug 959
+ * @todo Check for RFC 2822 compilance (bug 959)
If there is any objection to this, then I apologize, and it can be left as-is.
* @obsolete becomes @deprecated
Helps both. Doxygen does not seem to support @obsolete, but it does support @deprecated.
[Ref:
http://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecated ]
* Things like "/**@{{" and
"/**@}}*/" which cause "unknown tag" warnings were removed
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.
* @access must be a valid access level.
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.
* @desc tag not needed, removed.
Helps both. @desc does not seem to be supported by either Doxygen, or PHPDocumentor.
* Doesn't seem to like @licence, will accept
@license however.
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.
* Use full comment block notation in a few places
(i.e. open block with "/**", start each line with " *", and end block
with "
*/")
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.
* Moved some docs to right above those classes
(deleting blank lines, or moving descriptions from the file headers)
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.
* Marked some classes without docs as "@todo
document"
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.