Allow @param and @return docs on hook implementations

Created on 22 May 2019, about 5 years ago
Updated 8 November 2023, 8 months ago

Problem/Motivation

State what you believe is wrong or missing from the current standards.

Benefits

If we adopted this change, the Drupal Project would benefit by ...

Three supporters required

  1. https://www.drupal.org/u/ → {userid} (date that user added support)
  2. https://www.drupal.org/u/ → {userid} (date that user added support)
  3. https://www.drupal.org/u/ → {userid} (date that user added support)

Proposed changes

Provide all proposed changes to the Drupal Coding standards → . Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:

1. {link to the documentation heading that is to change}

Add current text in blockquotes

Add proposed text in blockquotes

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

  1. Add supporters
  2. Create a Change Record
  3. Review by the Coding Standards Committee
  4. Coding Standards Committee takes action as required
  5. Tagged with 'Needs documentation edits' if Core is not affected
  6. Discussed by the Core Committer Committee, if it impacts Drupal Core
  7. Documentation updates
    1. Edit all pages
    2. Publish change record
    3. Remove 'Needs documentation edits' tag
  8. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a fuller explanation of these steps see the Coding Standards project page →

==== Original template to be converted to the new template above and then removed ===

From https://www.drupal.org/docs/develop/standards/api-documentation-and-comm... →

Hook implementation
Documentation uses a short format:

/**
 * Implements hook_help().
 */
function blog_help($section) {

If appropriate, you can add additional details pertinent to the particular hook implementation in a separate paragraph after the summary. Do not document parameters and return value though -- these are documented on the hook definition referenced in the summary line.

I think this is bad advice, because

  • IDEs do not look at the hook definition for type hints (I am only speaking for the IDE I use myself).
  • In many cases (in D7 at least), the hook definition in old contrib modules is missing proper type hints on the @param and @return docs. So even if the IDE would try, it would find nothing.
  • As a human reading code, I don't want to jump to the hook definition all the time.

It should be possible for a contrib or custom module to add the @param and @return docs on a hook implementation, to get full support from the IDE and to clarify things that are missing in the hook definition doc.

I already do this in projects I maintain myself, but I don't want to be arguing with my team members or a client about it who (rightfully) point out what is currently the standard in Drupal.

It could be made explicit that this only applies to custom or contrib code and is optional.

✨ Feature request
Status

Active

Component

Coding Standards

Created by

🇩🇪Germany donquixote

Live updates comments and jobs are added and updated live.
  • Needs issue summary update

    Issue summaries save everyone time if they are kept up-to-date. See Update issue summary task instructions.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • 🇬🇧United Kingdom Alina Basarabeanu

    I need help with the hook implementation coding standards as I can't find a way to fix it
    Example:

    /**
     * Implements hook_page_attachments().
     */
    function test_page_attachments(array &$page): void {

    Error retund by the validation:
    Function test_page_attachments() does not have @param annotation for its traversable parameter $page.

    If I add the @param I get a different error:
    Hook implementations should not duplicate @param documentation

    How can I fix it?

  • Status changed to Needs work 10 months ago
  • 🇬🇧United Kingdom Alina Basarabeanu
  • 🇩🇪Germany DiDebru

    Same Issue for me as mentioned in #5.
    Also -1 for me maintain annotations is quite a lot of work.

  • Status changed to Active 9 months ago
  • 🇳🇴Norway steinmb

    Feature requests are "never" critical.

  • 🇮🇳India chetan 11

    /**
    * Implements hook_preprocess_HOOK() for page templates.
    *
    * Prepares variables for page templates.
    *
    * @param array &$variables
    * An associative array of variables for the page template.
    * - node: The node object, if there is an active node associated with the page.
    * - logged_in: A flag indicating whether the current user is logged in.
    * @param string $hook
    * The name of the theme hook being invoked. Typically "page".
    *
    * @see template_preprocess_page()
    */
    function mymodule_preprocess_page(&$variables, $hook) {
    // Implementation code here.
    }

    /**
    * Implements hook_menu().
    *
    * Defines menu items and page callbacks.
    *
    * @return array
    * An associative array describing menu items and their page callbacks.
    *
    * @see mymodule_menu()
    */
    function mymodule_menu() {
    $items = array();

    $items['example-page'] = array(
    'title' => 'Example Page',
    'page callback' => 'mymodule_example_page',
    'access callback' => 'user_access',
    'access arguments' => array('access content'),
    'type' => MENU_NORMAL_ITEM,
    );

    return $items;
    }

    /**
    * Page callback for the example page.
    *
    * @param array $args
    * An array of arguments passed from the URL path.
    *
    * @return string
    * The rendered content for the page.
    */
    function mymodule_example_page($args) {
    // Implementation code here.
    return 'Hello, this is the example page content.';
    }

  • 🇮🇹Italy apaderno Brescia, 🇮🇹

    Using PhpStorm, I get messages from the IDE for hooks. I still think it is a bad idea, to add @param and @return tags to hook implementations.
    Except in few cases where parameters can have a type that is more specific, in most of the cases, the parameter's types are the same for all the hook implementations. It also seems a feature that goes in the opposite direction taken when the documentation comment for class constructors has been done not mandatory.

  • 🇳🇿New Zealand quietone New Zealand

    The Coding Standards Committee has developed a custom issue template → to assist in managing issues efficiently. We have already found that it's use is helping. For issues created before the template was in use I am adding the new template to the Issue Summary and asking everyone here to help convert to it..

    Thank you for your help!

Production build 0.69.0 2024