Problem/Motivation
This META issue is a spin-off from #1792992: Are typed @param / @return part of the documentation gate? where several people voiced the view that all @param and @return directives in docblocks MUST include type hints. However, some stated that it only SHOULD be a suggestion since "core does not follow this standard yet." The focus of this META issue is to add missing type hinting to @param and @return directives throughout all of existing core documentation.
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 (10-15 as a guess).
Proposed resolution
Add type hinting for all @param and @return directives in a series of "small" patches.
How to's
How to review patches for this issue:
# This is a one-liner to aid in reviewing patches on this Drupal.org meta issue:
# https://www.drupal.org/node/1800046
# You can use netbeansdrupalcomposed to gather the dependencies, which are phpcs
# and Drupal's Coder module
# https://www.drupal.org/sandbox/mile23/2197899
# Substitute any module path you want in order to check only that module.
# The resulting list will be a bit of gobbledygook in CSV, but will show you whether
# or not the patch you're evaluating successfully removed the errors we're looking for.
phpcs --standard="/path/to/drupal/coder/coder_sniffer/Drupal" --extensions="module/php,inc/php,php" --report-csv path/to/module/ | grep -F $'Missing param\nReturn type missing'The above one-liner can also be found in this github gist: https://gist.github.com/paul-m/227822ac7723b0e90647
- Check that the parameters are identified correctly. For example, if the function signature is function_name($foo_bar), the parameter should be listed as $foo_bar in the docblock, not $foobar.
- Check that all parameters are documented, unless our standards explicitly specify omitting them (as with form constructors).
- Check that the parameters are in the order specified in the function signature.
- Read each parameter description and make sure that it is grammatically correct, clear English, with proper capitalization, punctuation, etc. (Each parameter description should form a complete English sentence if the words "This parameter is..." were to be added to the beginning, but those words should not be included in the docblock.) Keep an eye out for typos.
- Look up each function in the patch on api.drupal.org (D8). Read the function carefully and ensure that the parameter description properly documents how the parameter is used.
- Look at the type hint documented for each parameter. Make sure the types correspond to the allowed types at http://drupal.org/node/1354#param-return-data-type.
- Make sure all possibilities for the parameter are documented; for example, if the function optionally accepts a NULL value for a string parameter, then it should be documented as string|null.
- Also check the function's callers and string references (linked on api.d.o) and make sure the values being passed to the function are in the datatypes specified.
- Apply the patch to your local repository, and check that no other functions in these files are missing parameter documentation.
- Document what you reviewed and what you found specifically in your review comment.
Remaining Tasks
| Task | Novice task? | Contributor instructions | Complete? |
|---|---|---|---|
| Update the issue summary noting if allowed during the beta | Instructions |
