Contrib.social

Allow documentation on @see tags

Open on Drupal.org →
Created on 15 June 2016, about 8 years ago
Updated 16 August 2023, 11 months ago

Problem/Motivation

Currently @see tags are forbidden from having documentation.

Drupal standards: Each @see reference is on its own line, with no additional text beyond the item being referenced. To provide more explanation, just use a regular documentation paragraph.

https://www.drupal.org/coding-standards/docs#see →

From the rest of the documentation around the tag implies this is specifically because of its use for API module rather then allowing the tag to provide useful information to developers in other automated tools or when reading the code.

This can lead to unclear references. Why would a developer care to see the referenced method? Is only a specific part of a class relevant?

Additionally PSR5 suggests the opposite and says @see SHOULD have documentation so in additional to allowing for more clear documentation, this would bring the standard closer to PSR-4.

Proposed resolution

Fix API.module if this somehow breaks it.

Change the coding standards to remove the limitation and update coder's phpcs rule to reflect the change.

Comparison

For:

  1. Could be useful for making clearer documentation about why someone would want to look at the reference.
  2. More maintainable
  3. Agrees with draft PSR-5 standard, phpdoc, as well as some other non php parsers like jsdoc and rubydoc.
  4. Vs. doing it in prose, PHPStorm allows cross references of @see methods and classes but not in normal documentation.

Against:

  1. Even clearer documentation can be achieved with long form documentation. Longer descriptions and more context given.
  2. Would require change of code to API module (not all that difficult but still needs to be done, tested, deployed, etc.).
  3. Would require change to Coder sniffs (I think?).
  4. Unclear how many developers would actually use it (getting them to write more documentation is not usually easy).
📌 Task
Status

Active

Component

Coding Standards

Created by

🇺🇸United States neclimdul Houston, TX

Live updates comments and jobs are added and updated live.
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.

  • Comment 11 months ago →
    🇦🇹Austria mvonfrie

    I just came across this issue when getting the error message "The @see reference should not contain any additional text" from PHPCS for an internal project.

    I agree with #11 and understand all the pros and cons, though my failing use case of @see has not been discussed here and is somewhere in between. Like @Perignon → I use @see for links when it is necessary for the understanding of some code. But unfortunately those specific links are very long and difficult to read, especially in rendered documentation like from PhpStorm.

    Instead of

    @see https://difficult-to-read-and-remember.hostname.com/1236456/some-very-long-and-crazy-url-which-nobody-will-understand-the-meaning-of-by-reading-this

    I want to use

    @see {@link https://difficult-to-read-and-remember.hostname.com/1236456/some-very-long-and-crazy-url-which-nobody-will-understand-the-meaning-of-by-reading-this Descriptive name of the linked page}

    which then would be rendered as Descriptive name of the linked page (this link obviously doesn't work) linked to the given url.

contrib.social Blog FAQ Discussions
Production build 0.69.0 2024