Page MenuHomePhabricator

[REPO][CLIENT][SW] Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase
Open, Needs TriagePublic

Description

Since mediawiki-codesniffer v41 (T325201), those sniffs are more lenient about allowing missing doc comments as long as information is provided by static types, which removes the main reason we disabled them in Wikibase (I believe). We should reenable the sniffs, to catch legitimate errors like the following:

FILE: /var/www/html/wiki1/extensions/Wikibase/client/includes/Serializer/ClientEntitySerializer.php                                                                                                                                                                                                                                                        
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                                                                                                  
FOUND 2 ERRORS AFFECTING 2 LINES                                                                                                                                                                                                                                                                                                                           
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                                                                                                  
 36 | ERROR | Doc comment for parameter $filterLangCodes does not match actual variable name $entityIdParser (MediaWiki.Commenting.FunctionComment.ParamNameNoMatch)                                                                                                                                                                                       
 37 | ERROR | Doc comment for parameter $termFallbackChains does not match actual variable name $filterLangCodes                                                                                                                                                                                                                                           
    |       | (MediaWiki.Commenting.FunctionComment.ParamNameNoMatch)                                                                                                                                                                                                                                                                                      
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                                                                                                  

FILE: /var/www/html/wiki1/extensions/Wikibase/client/includes/Store/DescriptionLookup.php                                                                                                                                                                                                                                                                  
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                                                                            
FOUND 2 ERRORS AFFECTING 2 LINES                                                                                                                                                                                                                                                                                                                           
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                                                                            
  67 | ERROR | [x] Pass-by-reference for parameter $actualSources does not match pass-by-reference of variable name $actualSources                                           
     |       |     (MediaWiki.Commenting.FunctionComment.ParamPassByReference)                                                                                                                                                                                                                                                                             
 105 | ERROR | [x] Pass-by-reference for parameter $actualSource does not match pass-by-reference of variable name $actualSource                                                                                                                                                                                                                           
     |       |     (MediaWiki.Commenting.FunctionComment.ParamPassByReference)                                                                                                                                                                                                                                                                             
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                                                                            
PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY                                                                                                                                                                                                                                                                                                 
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

And also to discover places where neither a doc comment nor a static type is present – though in most cases, I expect we’ll want to resolve those errors by adding static types, not doc comments.

Event Timeline

Change 892384 had a related patch set uploaded (by Lucas Werkmeister (WMDE); author: Lucas Werkmeister (WMDE)):

[mediawiki/extensions/Wikibase@master] WIP: Reenable documentation sniffs

https://gerrit.wikimedia.org/r/892384

See this CI build for a list of errors / violations (as of PS1 of the above change).

Add $snakNamespace to ValueSnakRdfBuilder::addValue PHPDoc is an example of the kind of mistake / fix that this sniff would prevent, I think.

Lucas_Werkmeister_WMDE renamed this task from Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase to [REPO][CLIENT][SW] Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase.Tue, Apr 16, 12:03 PM