[REPO] [CLIENT] Reenable FunctionComment and Cleanup PropertyDocumentation phpcs sniffs in Wikibase
Closed, ResolvedPublic
Actions

Assigned To

Authored By

	Lucas_Werkmeister_WMDE
	Feb 27 2023, 11:02 AM

Description

Since mediawiki-codesniffer v41 (T325201), the FunctionComment and Cleanup PropertyDocumentation 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 ones seen below, as well as to discover places where neither a doc comment nor a static type is present.

Acceptance Criteria:

MediaWiki.Commenting.FunctionComment.ParamNameNoMatch sniff is enabled in Wikibase
MediaWiki.Commenting.FunctionComment.ParamPassByReference sniff is enabled in Wikibase
All violations of these rules are fixed
Remove any comments that were added in change 1064919 and replace them with type hints

Notes:

In most cases we’ll want to resolve errors by adding static types, not doc comments.
Example of legitimate violations:

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

Details

Related Changes in Gerrit:

Subject	Repo	Branch	Lines +/-
Reenable documentation sniffs	mediawiki/extensions/Wikibase	master	+463 -97
Replace phpdoc types with type annotations for private members	mediawiki/extensions/Wikibase	master	+140 -252
Add function documentation to function params	mediawiki/extensions/Wikibase	master	+49 -4
WIP: Reenable documentation sniffs	mediawiki/extensions/Wikibase	master	+8 -3
Add function documentation to private functions	mediawiki/extensions/Wikibase	master	+170 -1

Customize query in gerrit

Related Objects

Mentioned Here: T325201: Make release v41.0.0 of mediawiki/mediawiki-codesniffer

Event Timeline

Lucas_Werkmeister_WMDE created this task.Feb 27 2023, 11:02 AM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptFeb 27 2023, 11:02 AM

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

gerritbot added a project: Patch-For-Review.Feb 27 2023, 11:08 AM

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

Michael subscribed.Feb 27 2023, 11:23 AM

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 edited projects, added wmde-wikidata-tech; removed [DEPRECATED] wdwb-tech.Apr 12 2024, 1:58 PM

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.Apr 16 2024, 12:03 PM

Lucas_Werkmeister_WMDE moved this task from Incoming to [DOT] By Project on the wmde-wikidata-tech board.

Lucas_Werkmeister_WMDE added a project: [Archived]Wikidata Dev Team.

Arian_Bozorg moved this task from Incoming to [DOT] Tech Backlog on the [Archived]Wikidata Dev Team board.Apr 23 2024, 1:08 PM

removed from dev board until its can go through our prioritization pipeline

ItamarWMDE moved this task from [DOT] By Project to Wikidata Omega Triage on the wmde-wikidata-tech board.Dec 4 2024, 11:42 AM

ItamarWMDE edited projects, added wmde-wikidata-tech (Wikidata Omega Triage); removed wmde-wikidata-tech.

ItamarWMDE moved this task from Incoming to Repo on the wmde-wikidata-tech (Wikidata Omega Triage) board.Dec 4 2024, 2:09 PM

ItamarWMDE moved this task from Repo to Infrastructure on the wmde-wikidata-tech (Wikidata Omega Triage) board.Dec 4 2024, 3:24 PM

ItamarWMDE moved this task from Infrastructure to UX Staging on the wmde-wikidata-tech (Wikidata Omega Triage) board.Dec 6 2024, 10:43 AM

ItamarWMDE moved this task from UX Staging to Checks Completeness on the wmde-wikidata-tech (Wikidata Omega Triage) board.

ItamarWMDE updated the task description. (Show Details)Dec 6 2024, 10:52 AM

Prio Notes:

Impact Area	Affected
production / end users	no
monitoring	no
development efforts	yes
onboarding efforts	no
additional stakeholders	no

ItamarWMDE triaged this task as Low priority.Dec 6 2024, 10:54 AM

ItamarWMDE renamed this task from [REPO][CLIENT][SW] Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase to [SW][REPO][CLIENT] Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase.Dec 6 2024, 11:59 AM

ItamarWMDE renamed this task from [SW][REPO][CLIENT] Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase to [SW] [REPO] [CLIENT] Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase.

ItamarWMDE moved this task from Checks Completeness to Prioritized - Moving a task here moves the ticket to Wikidata Dev and removes it from this board on the wmde-wikidata-tech (Wikidata Omega Triage) board.

ItamarWMDE edited projects, added [Archived]Wikidata Dev Team; removed wmde-wikidata-tech (Wikidata Omega Triage).

ItamarWMDE renamed this task from [SW] [REPO] [CLIENT] Reenable FunctionComment and PropertyDocumentation phpcs sniffs in Wikibase to [REPO] [CLIENT] Reenable FunctionComment and Cleanup PropertyDocumentation phpcs sniffs in Wikibase.Dec 12 2024, 11:58 AM

ItamarWMDE updated the task description. (Show Details)

ItamarWMDE moved this task from [DOT] Tech Backlog to SEND TO OMEGA BOARD. Will land in the 'incoming' column and need to be moved to the correct location (former Unified DOT Backlog) on the [Archived]Wikidata Dev Team board.

Change #1112357 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/Wikibase@master] Add function documentation to private functions

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

ArthurTaylor claimed this task.Feb 27 2025, 10:09 AM

ArthurTaylor edited projects, added [Archived]Wikidata Dev Team (Wikidata.org Slice); removed [Archived]Wikidata Dev Team.

ArthurTaylor moved this task from In Task Breakdown to In Development on the [Archived]Wikidata Dev Team (Wikidata.org Slice) board.

Change #1123327 had a related patch set uploaded (by Arthur taylor; author: Arthur taylor):

[mediawiki/extensions/Wikibase@master] Replace phpdoc types with type annotations for private members

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

Change #1112357 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] Add function documentation to private functions

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

ReleaseTaggerBot added a project: MW-1.44-notes (1.44.0-wmf.19; 2025-03-04).Feb 27 2025, 1:00 PM

Change #1123360 had a related patch set uploaded (by Arthur taylor; author: Lucas Werkmeister (WMDE)):

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

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

Change #892384 abandoned by Arthur taylor:

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

Reason:

Replaced with Ie54947ebd3650976c0c5569408e690ad9b039e38 - sorry for the confusion!

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

ArthurTaylor removed ArthurTaylor as the assignee of this task.Feb 27 2025, 2:05 PM

ArthurTaylor moved this task from In Development to Ready for Development on the [Archived]Wikidata Dev Team (Wikidata.org Slice) board.

ArthurTaylor subscribed.

Change #1123462 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/Wikibase@master] Add function documentation to function params

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

ArthurTaylor claimed this task.Mar 4 2025, 8:00 AM

ArthurTaylor moved this task from Ready for Development to In Development on the [Archived]Wikidata Dev Team (Wikidata.org Slice) board.

ArthurTaylor removed ArthurTaylor as the assignee of this task.Mar 4 2025, 11:59 AM

ArthurTaylor moved this task from In Development to Ready for Peer Review on the [Archived]Wikidata Dev Team (Wikidata.org Slice) board.

Change #1123462 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] Add function documentation to function params

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

ReleaseTaggerBot edited projects, added MW-1.44-notes (1.44.0-wmf.20; 2025-03-11); removed MW-1.44-notes (1.44.0-wmf.19; 2025-03-04).Mar 4 2025, 3:00 PM

Change #1123327 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] Replace phpdoc types with type annotations for private members

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

ArthurTaylor assigned this task to Lucas_Werkmeister_WMDE.Mar 6 2025, 8:22 AM

ArthurTaylor moved this task from Ready for Peer Review to In Peer Review on the [Archived]Wikidata Dev Team (Wikidata.org Slice) board.

Change #1123360 merged by jenkins-bot:

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

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

MediaWiki.Commenting.FunctionComment.ParamPassByReference sniff is enabled in Wikibase

I’m not really sure what this is doing in the acceptance criteria tbh, given that AFAICT we never disabled it specifically in Wikibase… I guess it comes from the time before this change, because we originally disabled the whole FunctionComment sniff instead of only parts of it? But anyway, I think it’s enabled now (comes with mediawiki-codesniffer and we don’t disable it).

Maintenance_bot removed a project: Patch-For-Review.Mar 6 2025, 2:32 PM

karapayneWMDE closed this task as Resolved.Mar 7 2025, 3:21 PM

karapayneWMDE assigned this task to ArthurTaylor.

karapayneWMDE moved this task from Ready for Tech Verification to In Tech Verification on the [Archived]Wikidata Dev Team (Wikidata.org Slice) board.

karapayneWMDE moved this task from In Tech Verification to Done on the [Archived]Wikidata Dev Team (Wikidata.org Slice) board.

[REPO] [CLIENT] Reenable FunctionComment and Cleanup PropertyDocumentation phpcs sniffs in WikibaseClosed, ResolvedPublicActions

Description

Details

Related Objects

Event Timeline

[REPO] [CLIENT] Reenable FunctionComment and Cleanup PropertyDocumentation phpcs sniffs in Wikibase
Closed, ResolvedPublic
Actions