@param documentation

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

@param documentation

Jeremy Postlethwaite-2
Hello!

In the Mediawiki coding conventions section on PHP, the format for @param
tag is not what Doxygen recommends.

http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#Comments_and_Documentation

We have:

General format for parameters is such: @param $varname [type]: [description].
Multiple types can be listed by separating with a pipe character.

I added a note in the document:

Doxygen documentation states that @param should have the same format as
phpDocumentor[1]<http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#cite_note-0>
:


@param  datatype1|datatype2 $paramname description

How should we deal with this?

Thanks.

--
Jeremy Postlethwaite
[hidden email]
415-839-6885 x6790
Backend Software Developer
Wikimedia Foundation <http://wikimediafoundation.org/>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Ryan Kaldari-2
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

On 4/25/12 3:52 PM, Jeremy Postlethwaite wrote:

> Hello!
>
> In the Mediawiki coding conventions section on PHP, the format for @param
> tag is not what Doxygen recommends.
>
> http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#Comments_and_Documentation
>
> We have:
>
> General format for parameters is such: @param $varname [type]: [description].
> Multiple types can be listed by separating with a pipe character.
>
> I added a note in the document:
>
> Doxygen documentation states that @param should have the same format as
> phpDocumentor[1]<http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#cite_note-0>
> :
>
>
> @param  datatype1|datatype2 $paramname description
>
> How should we deal with this?
>
> Thanks.
>

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Christian Aistleitner
Hi,

On Wed, Apr 25, 2012 at 05:25:16PM -0700, Ryan Kaldari wrote:
> I would support moving to the correct syntax though, as we shouldn't
> keep using the wrong one forever.

I'd also love to be able to use the doxygen suggested syntax.

Then Doxygen's generated HTML output would nicely align not only
parameter type, and parameter name (as we currently have), but also
the parameter description itself.

The HTML output would finally also match the order used for PHP type
hinting.

Besides it would make life easier for devs using IDEs, as some IDEs
support doxygen's order.

> Plus new hires are going to use the
> up-to-date syntax anyway (until we train them not too).

Been there. Fell into this trap as well :(

Kind regards,
Christian



--
---- quelltextlich e.U. ---- \\ ---- Christian Aistleitner ----
                           Companies' registry: 360296y in Linz
Christian Aistleitner
Gruendbergstrasze 65a        Email:  [hidden email]
4040 Linz, Austria           Phone:          +43 732 / 26 95 63
                             Fax:            +43 732 / 26 95 63
                             Homepage: http://quelltextlich.at/
---------------------------------------------------------------

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

signature.asc (501 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Krinkle
In reply to this post by Ryan Kaldari-2
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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Happy Melon-2
On 26 April 2012 20:59, Krinkle <[hidden email]> wrote:

>
> 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.
>

This gives me not-entirely-pleasant reminders of "string" verses "String"
in C#...

Another thing that's worth thinking about is how to indicate that the
variable is an array of some uniform type.  We have a lot of
"Array(Title)", etc; but my IDE at least doesn't catch all that information
and only type-hints as far as it being an array.  It prefers, and fully
parses, the syntax "Title[]"; but does that work in Doxygen?

--HM
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Ryan Kaldari-2
In reply to this post by Krinkle
On 4/26/12 12:59 PM, Krinkle wrote:
> 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.

We definitely shouldn't migrate to "@param type $var: description"
because that's not valid doxygen syntax. The correct syntax is without a
colon. This is why your 2nd example ends up with mangled output. If we
follow the correct syntax, it should output fine. And since we're using
the standard doxygen parser, the only argument I can see for sticking
with the old syntax is because "we've been doing it for years", which
isn't very convincing.

Ryan Kaldari

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Jeremy Postlethwaite-2
The third example from Krinkle looks like the only one being parsed
correctly :)

On Thu, Apr 26, 2012 at 4:16 PM, Ryan Kaldari <[hidden email]>wrote:

> On 4/26/12 12:59 PM, Krinkle wrote:
>
>> 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.
>>
>
> We definitely shouldn't migrate to "@param type $var: description" because
> that's not valid doxygen syntax. The correct syntax is without a colon.
> This is why your 2nd example ends up with mangled output. If we follow the
> correct syntax, it should output fine. And since we're using the standard
> doxygen parser, the only argument I can see for sticking with the old
> syntax is because "we've been doing it for years", which isn't very
> convincing.
>
> Ryan Kaldari
>
>
> ______________________________**_________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/**mailman/listinfo/wikitech-l<https://lists.wikimedia.org/mailman/listinfo/wikitech-l>
>



--
Jeremy Postlethwaite
[hidden email]
415-839-6885 x6790
Backend Software Developer
Wikimedia Foundation <http://wikimediafoundation.org/>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Niklas Laxström
In reply to this post by Ryan Kaldari-2
On 27 April 2012 02:16, Ryan Kaldari <[hidden email]> wrote:
> We definitely shouldn't migrate to "@param type $var: description" because
> that's not valid doxygen syntax. The correct syntax is without a colon. This
> is why your 2nd example ends up with mangled output. If we follow the
> correct syntax, it should output fine. And since we're using the standard
> doxygen parser, the only argument I can see for sticking with the old syntax
> is because "we've been doing it for years", which isn't very convincing.

This gives me headache:
@param $title Title Title for the method
There is no separation between the type and description, which makes
it hard to read and want to use the type as part of the description

So +1 for:
@param Title $title Title for the method.

  -Niklas

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: @param documentation

Andrew Garrett-4
In reply to this post by Jeremy Postlethwaite-2
On Thu, Apr 26, 2012 at 8:52 AM, Jeremy Postlethwaite <
[hidden email]> wrote:

> Hello!
>
> In the Mediawiki coding conventions section on PHP, the format for @param
> tag is not what Doxygen recommends.
>
>
> http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#Comments_and_Documentation
>
> We have:
>
> General format for parameters is such: @param $varname [type]:
> [description].
> Multiple types can be listed by separating with a pipe character.
>
> I added a note in the document:
>
> Doxygen documentation states that @param should have the same format as
> phpDocumentor[1]<
> http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#cite_note-0>
> :
>
>
> @param  datatype1|datatype2 $paramname description
>
> How should we deal with this?
>

Unlike Java, which doxygen was originally developed for, PHP is a weakly
typed language. Often, a function parameter can take multiple types.

So actually, I'd be in favour of the status quo, which is to specify the
type as part of the description.

So instead of:
@param $title Title Title for the method
or
@param Title $title Title for the method.

We should use:
@param $title Title object to use for the method.

—Andrew

--
Andrew Garrett
Wikimedia Foundation
[hidden email]
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l