Voting starts in March for the Drupal Association Board election.
For a variety of reasons,
@return documentation should include the data type. Although this is mentioned in coding standards, it is not mandated. This issue started with a patch to add data types to all the
@return lines in the
includes/file.inc file, but it has subsequently morphed into a discussion of the question, "Should all
@return data types be documented?"
- In favor of the standards change:
- Opposed to the standards change:
- Thinks the standards change is desirable but impractical:
Note that the above was gathered by inference; Feel free to revise if you know differently.
The proposed patch adds parameter and return data type documentation to the
- The patch in this issue needs to be reviewed, approved, and committed.
- Similar patches should be generated for the rest of Drupal core.
- The Documenting functions and methods documentation should be rewritten to reflect that:
- Type hinting in
@returnlines is now required rather than merely allowed.
mixedtype-hint is now deprecated and should be replaced with the allowed types separated by the vertical-bar character, as
boolis preferred over
boolean, according to webchick and PEAR.
intis preferred over
- Type hinting in
- A patch should be written to create a D8 version of Coder that warns if such type-hinting is missing or
User interface changes
None; this is a documentation change only. Adding data types to actual function arguments should be considered in separate issues.
Per jhodgdon in :
maybe rewrite it as:
@param string $uri
And in #35:
Having data types in @param statements is a relatively new doc standard. There is no real reason why it shouldn't be adopted here, just because it hasn't been adopted everywhere else yet.