Quantcast

MediaWiki-Codesniffer 0.8.0 released

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

MediaWiki-Codesniffer 0.8.0 released

Legoktm
Hi,

MediaWiki-Codesniffer 0.8.0 is now available for use in your MediaWiki
extensions and other projects. Here's the full list of changes since the
last release (0.8.0-alpha.1):

* Add sniff for cast operator spacing (Sam Wilson)
* Allow filtering documentation requirements based on visibility (Kunal
Mehta)
* Don't require documentation for test cases (Kunal Mehta)
* Don't require @return annotations for plain "return;" (Kunal Mehta)
* Explicitly check for method structure before using (Sam Wilson)
* Fix test result parsing, and correct new errors that were exposed (Sam
Wilson)
* Prevent abstract functions being marked eligible (Sam Wilson)
* PHP_CodeSniffer to 2.9.0 (Paladox)

This release contains a lot of new rules documenting functions and
ensuring parameters and return types are specified. It's most likely
that existing code will not pass the new rulset without documentation
improvements (see MediaWiki Documentation Day email ;)).

If you encounter any bugs or have suggestions on new rules, please reply
to this thread or file a bug in the #MediaWiki-Codesniffer Phabricator
project.

Thanks,
-- Legoktm

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

Re: MediaWiki-Codesniffer 0.8.0 released

Brad Jorsch (Anomie)
On Thu, May 4, 2017 at 5:14 PM, Legoktm <[hidden email]> wrote:

> If you encounter any bugs or have suggestions on new rules, please reply
> to this thread or file a bug in the #MediaWiki-Codesniffer Phabricator
> project.
>

I ran this over a few repositories and ran into some issues.

   - "@param string $name" seems fine on a method like "getItemByName()",
   there's little point in making that "@param string $name The name"
   - It whines if PHP builtins aren't documented. Do we really need to
   document __toString() over and over again?
   - 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.

At that point I gave up looking for wheat in the chaff.
--
Brad Jorsch (Anomie)
Senior Software Engineer
Wikimedia Foundation
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: MediaWiki-Codesniffer 0.8.0 released

Legoktm
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. :/

>    - 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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: MediaWiki-Codesniffer 0.8.0 released

Tom Bishop, Wenlin Institute

> On May 6, 2017, at 12:25 PM, Legoktm <[hidden email]> 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
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l


Wenlin Institute, Inc. SPC (a Social Purpose Corporation)
文林研究所社会目的公司
Software for Learning Chinese
E-mail: [hidden email]     Web: http://www.wenlin.com
Telephone: 1-877-4-WENLIN (1-877-493-6546)




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