Contrib.social

Introduce @was phpDoc directive to link/reference to previous/renamed functions

Open on Drupal.org →
Created on 4 May 2012, about 12 years ago
Updated 21 June 2024, 7 days ago

Problem

  • Renamed functions are hard to figure out in the API documentation.
  • Writing change notices for "foo() was renamed to bar()." is absurd.

Goal

  • Make it easier to identify simple API changes of renamed functions.
  • Omit change notices for functions that were renamed only.

Examples

Details

  • At least Doxygen's command list does not state any command that would come close to this.
  • However, it's perfectly valid to extend the parser with custom aliases. @xrefitem adds a reference to a custom reference list. To not repeat that everywhere, a Doxygen config (if any) would define:
    ALIASES += "was=\xrefitem was \"Was previously\" \"Renamed functions\""

Proposed solution

  1. Introduce @was directive (sharing semantics with any other \sa reference; e.g., @see).
  2. Add @was directives to all renamed functions in core; e.g.:
    /**
 * ...
 *
 * @was menu_rebuild()
 */
function menu_router_build() {
  3. Make Coder Upgrade query and pull in the current list of @was references directly from api.drupal.org and use a generic review rule to warn that $before became $after.
  4. Delete all change notices that are about renames only.

Related issues

📌 Task
Status

Closed: won't fix

Component

Documentation

Created by

🇩🇪Germany sun Karlsruhe

Live updates comments and jobs are added and updated live.
  • Coding standards

    It involves compliance with, or the content of coding standards. Requires broad community agreement.

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 7 days ago →
    🇳🇿New Zealand quietone New Zealand

    This was discussed at the Coding Standards meeting #3456119: Coding Standards Meeting Tuesday 2024-06-18 2100 UTC → by myself, mstrelan, Björn Brala (bbrala) and borisson_.

    There was concern about keeping around references to old code. And there was also acknowledgement that we have improved tools for tracking renaming and/or deprecating things so that it seems unnecessary to add '@was'. We concluded that with deprecation notices, change records and static analysis this is not needed. And further, the tools to help here continue to evolve.

    Therefor, closing as won't fix.

contrib.social Blog FAQ Discussions
Production build 0.69.0 2024