krinklemail at gmail
Apr 26, 2012, 12:59 PM
Post #4 of 9
(123 views)
Permalink
|
On Apr 26, 2012, at 2:25 AM, Ryan Kaldari wrote:
> Krinkle and I went back and forth on this one last year. Apparently, it's a bit of a bootstrapping problem since all of our comments are currently written the wrong way (due to an old bug in doxygen that has since been fixed), and thus our comment parser expects them to be in the wrong format. Krinkle can elaborate.
>
> I would support moving to the correct syntax though, as we shouldn't keep using the wrong one forever. Plus new hires are going to use the up-to-date syntax anyway (until we train them not too).
>
> Ryan Kaldari
>
What do you mean by "parser expects" ? We're just using Doxygen, and Doxygen
doesn't do anything fancy in the HTML output with the values in @param, it
doesn't care about the order. The only thing Doxygen does is parse the whole
text and linkify any classes. But it does that no matter where it is. So in
"@param $foo Title" it will turn "Title" into a link to class_Title. But it will
also do that in any of these cases:
* @param $foo Title: foo bar baz quux
* @param $foo Title foo bar baz quux
* @param Title $foo: foo bar baz quux
* @param Title $foo foo bar baz quux
* @param $foo foo bar baz Title quux
It doesn't appear to consider anything to be the "type" or the "$variable".
The only thing Doxygen does is extract the first space-separated part from the
@param line and italize it and put it in a different table column so that they
align nicely, but whether this is the type or the $variable doesn't matter.
Another aspect that is often inconsistent is that some people prefer to
uppercase primative types (so instead of "string", "array", "Title", they use
"Mixed", "Number", "String", "Array"). I find that somewhat confusing, but not
sure if we should enforce that in the conventions.
Few examples of different formats used in core, and how Doxygen parses it.
1)
* Action::factory
- Uses: @param $var type
- Source: https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=includes/Action.php;h=a25e8aa9ab3698a894f63535d6b6007cbd723044;hb=HEAD#l75
- Doxygen: https://svn.wikimedia.org/doc/classAction.html#a1fe6031d033c0721e4e1572938d44990
* Screenshot: http://i.imgur.com/YcJsK.png
I could find only one example of "@param type $var" that included a classname as
type and a colon before the description, and it didn't look very good in Doxygen,
no idea what's going on here:
2)
* CategoryViewer::addFragmentToTitle
* Uses: @param Type $var: description
* Source: https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=includes/CategoryViewer.php;h=dff38028cd0844ded42623c80817029c5f6aa702#l592
* Doxygen: https://svn.wikimedia.org/doc/classCategoryViewer.html#ae2fd8eb7171b011437c292b93ff6636b
* Screenshot: http://i.imgur.com/Afuke.png
One other example of @param without a description that didn't break
Doxygen apparantly:
3)
* Xml:: languageSelector
* Uses: @param type $var Description
* Source: https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=includes/Xml.php#l188
* Doxygen: https://svn.wikimedia.org/doc/classXml.html#a0d645accd9e487ebfa8d43819ae0d6d4
* Screenshot: http://i.imgur.com/8305q.png
I'm not confinced (yet) that we should migrate to "@param type $var:
description". Putting the type after the variable works just fine and we've been
doing it for years, and in at least one case (the second one in the above
summary) the Doxygen parser actually chokes on it for whatever reason.
-- Krinkle
_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
|
signature.asc
