This is a sub-issue of #1800046: [META] Add missing type hinting to core docblocks, fix Drupal.Commenting.FunctionComment.Missing* focused on correctly adding @param and @return type hinting to the Node module.

Documentation patches that include type hinting are time consuming to both review and commit because one must dig into the actual code to confirm that the type hints are both correct and complete. Hence, please be patient and try to limit type hint patches to covering only a limited number of docblocks (20-25 as a guess).

How To Review This Issue

  1. Attempt to apply the patch to see if it needs a reroll.
  2. Use the phpcs one-liner to evaluate whether all the relevant standards errors have been resolved: https://gist.github.com/paul-m/227822ac7723b0e90647
  3. Look at each change and determine whether the type hint is correct.

Related sprint issues:

Sprint Topic Sub Issue
#1518116: [meta] Make Core pass Coder Review #1533254: Make node module pass Coder Review
#1310084: [meta] API documentation cleanup sprint #1313980: Clean up API docs for node module
#500866: [META] remove t() from assert message #1797200: Remove t() from assertion messages in node.module tests
CommentFileSizeAuthor
#25 1800546-25.patch12.81 KBidebr
#25 interdiff-18-25.txt4.87 KBidebr
#18 1800546_18.patch11.06 KBMile23
#10 interdiff.txt13.98 KBMile23
#10 1800546_10.patch15.44 KBMile23
#8 node-api-1800546-8.patch2.79 KBadci_contributor
#8 1800546-5-8.txt980 bytesadci_contributor
#5 1800546-node-api.patch2.01 KBJalandhar
#2 1800546-2-th-node-api.patch8.51 KBLars Toomre
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Lars Toomre’s picture

Lars Toomre CreditAttribution: Lars Toomre commented
Issue summary: View changes

Added tags to Related issues title.

Lars Toomre’s picture

Lars Toomre CreditAttribution: Lars Toomre commented

Added a patch at #1313980-71: Clean up API docs for node module that is focused on docblock corrections and modifications. Once that has been committed, my plan is to add a patch here that adds missing type hinting to @param and @return directives as appropriate.

Lars Toomre’s picture

Lars Toomre CreditAttribution: Lars Toomre commented
Status: Active » Needs review
FileSize
1800546-2-th-node-api.patch8.51 KB

Attached is a patch that adds type hinting to the hook examples in node.api.php. This is untested locally, but should pass since all of the changes are in comments. Let's see what the bot thinks.

Lars Toomre’s picture

Lars Toomre CreditAttribution: Lars Toomre commented
Issue summary: View changes

Corrected the issue tags.

xjm’s picture

xjm
she/her
Primary language English
CreditAttribution: xjm commented
Component: node.module » node system
Issue summary: View changes

(Merging "node system" and "node.module" components for 8.x; disregard.)

Jalandhar’s picture

Jalandhar CreditAttribution: Jalandhar commented
Status: Needs review » Needs work
Issue tags: +Needs reroll

Patch no longer applies. It needs reroll.

Jalandhar’s picture

Jalandhar CreditAttribution: Jalandhar commented
Status: Needs work » Needs review
Issue tags: -Needs reroll
FileSize
1800546-node-api.patch2.01 KB

There is an inconsistency in the addition of type hinting in node.api.php file. Fixed the issues related to it and updating the patch.

Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 commented
Parent issue: » #1800046: [META] Add missing type hinting to core docblocks, fix Drupal.Commenting.FunctionComment.Missing*
Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 commented
Status: Needs review » Needs work

Amazingly, the patch in #5 still applies.

It doesn't catch all the needed type hints, though.

adci_contributor’s picture

adci_contributor CreditAttribution: adci_contributor commented
Status: Needs work » Needs review
FileSize
1800546-5-8.txt980 bytes
node-api-1800546-8.patch2.79 KB

Please review

Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 commented
Status: Needs review » Needs work

Thanks.

So, it's the whole module we're dealing with, not just the api file.

phpcs says to have a look in:

/src/NodeStorageInterface.php
/src/Plugin/views/argument/Vid.php
/node.module /src/NodeAccessControlHandlerInterface.php
/src/Tests/NodeAccessBaseTableTest.php
/src/Plugin/Search/NodeSearch.php
/src/NodeForm.php
Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 commented
FileSize
1800546_10.patch15.44 KB
interdiff.txt13.98 KB

Reroll of #8, plus a bunch more work.

This should get all missing parameter hints.

Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 commented
Status: Needs work » Needs review
Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 commented
Issue summary: View changes
nitvirus’s picture

nitvirus CreditAttribution: nitvirus at Srijan | A Material+ Company commented
Status: Needs review » Reviewed & tested by the community

Patch is working.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 10: 1800546_10.patch, failed testing.

no_angel’s picture

no_angel CreditAttribution: no_angel as a volunteer commented
no_angel’s picture

no_angel CreditAttribution: no_angel as a volunteer commented
Assigned: Unassigned » no_angel
no_angel’s picture

no_angel CreditAttribution: no_angel as a volunteer commented
Assigned: no_angel » Unassigned
Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 as a volunteer commented
Version: 8.0.x-dev » 8.1.x-dev
Status: Needs work » Needs review
FileSize
1800546_18.patch11.06 KB

Reroll of #10, plus one error I found.

Based on the gist in the issue summary, no remaining @param or @return type hinting errors.

Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 as a volunteer commented
Version: 8.1.x-dev » 8.0.x-dev

As with the other issues for the parent meta, moving this to 8.0.x. Patch still applies cleanly.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

idebr’s picture

idebr CreditAttribution: idebr at iO commented
Version: 8.5.x-dev » 8.6.x-dev
FileSize
interdiff-18-25.txt4.87 KB
1800546-25.patch12.81 KB

Reroll against 8.6.x.

Fixed the following sniffs in the Node module:

  1. Drupal.Commenting.FunctionComment.InvalidNoReturn
  2. Drupal.Commenting.FunctionComment.InvalidTypeHint
  3. Drupal.Commenting.FunctionComment.MissingParamComment
  4. Drupal.Commenting.FunctionComment.MissingParamType
  5. Drupal.Commenting.FunctionComment.MissingReturnComment
  6. Drupal.Commenting.FunctionComment.MissingReturnType
  7. Drupal.Commenting.FunctionComment.ParamMissingDefinition

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Status: Needs review » Closed (duplicate)
Related issues: +#3207949: Fix Drupal.Commenting.FunctionComment.MissingParamType

This work is now being done by sniff. The work here is now in #3207949: Fix Drupal.Commenting.FunctionComment.MissingParamType so closing this as a duplicate. I've identified credit to add over there, let me know if I got it wrong.