On May 6, 2017, at 12:25 PM, Legoktm
<legoktm.wikipedia(a)gmail.com> wrote:
Hi,
On 05/05/2017 01:38 PM, Brad Jorsch (Anomie) wrote:
I ran this over a few repositories and ran into
some issues.
Thanks for testing :)
- "@param string $name" seems fine on a method like
"getItemByName()",
there's little point in making that "@param string $name The name"
That makes sense. I'm just not sure how we could identify whether a
parameter is trivial and doesn't need documentation versus those that do. :/
I didn't find a link to the MediaWiki-Codesniffer 0.8.0 source in this email thread,
and I didn't find the method in question when I made a quick search, so I don't
have any context to go by. All the same, I'm saying this as someone frequently
frustrated by the lack of helpful comments in MediaWiki source code. Even if a parameter
seems trivial, its purpose, meaning, format, etc., might not be obvious to someone reading
the code later. The name of what? If it's the name of the item, "the name of the
item" would be an improvement over "the name". What kind of item? If
it's a menu item, "the name of the menu item" would be a further
improvement.
Best wishes,
Tom
- It whines if PHP builtins aren't
documented. Do we really need to
document __toString() over and over again?
Stuff like __toString()? No. Filed T164650 for that. But documentation
is needed for things like __construct. And if you're overriding magic
methods like __get you probably want to explain why.
- Doxygen is happy to inherit documentation
from the parent class for an
overridden method. Your phpcs check doesn't even honor @inheritdoc, it want
everything copied.
Filed as T164649.
-- Legoktm
_______________________________________________
Wikitech-l mailing list
Wikitech-l(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wenlin Institute, Inc. SPC (a Social Purpose Corporation)
文林研究所社会目的公司
Software for Learning Chinese
E-mail: wenlin(a)wenlin.com Web:
http://www.wenlin.com
Telephone: 1-877-4-WENLIN (1-877-493-6546)
☯