Contrib.social

Improve support for aliased methods

Open on Drupal.org →
Created on 31 August 2024, about 1 year ago

Problem/Motivation

Improve support for aliased methods.

If a class uses a trait, but aliases a method of the trait,

  1. searching for the alias does not yield any results. This makes it unnecessarily difficult to find the actual documentation / look at the implementation of an aliased method.
  2. the API page for the original method name doesn't list the aliases. Usages of the method don't indicate whether the original name or the aliased name is used. This might be confusing if you are searching for examples for how to use an aliased method and click through to an API page allegedly using the method, but you don't find the original method name in the implementation, only the alias, which you might not know about.
  3. the "Title" column on the API page for the class using the trait displays the original name of the method. The alias is displayed in the "Member alias" column. This might lead users to the wrong conclusion that the trait method is used as is, if they only look at the "Title" column. This is especially true for users using smaller screens where the relevant "Member alias" column of the table is not immediately visible, but requires scrolling. If you search the page for ::aliasedMethodName to quickly jump to the API page link for the method you are looking for, you will find nothing.

Steps to reproduce

One example in 11.x is \Drupal\Tests\BrowserTestBase, that aliases many methods from traits, e.g. UserCreationTrait::createUser, is aliased as BrowserTestBase::drupalCreateUser.

Proposed resolution

  1. Index aliased methods as ClassName::aliasedMethodName. This could either link to the API page for the original method after 2) has been resolved (preferred) or to a separate API page using the aliased method name that mentions that the method is actually an alias of TraitName::originalMethodName (not ideal, but might be easier to implement and better than nothing).
  2. Add a new section listing aliases in the form of \Namespace\Of\ClassName::aliasedMethodName to the API page of the original method name. Bonus: Split usages by originalMethodName and all known aliasedMethodNames, so that users can immediately see how often the original name and each aliased name is used respectively.
  3. Several possible solutions. Some ideas: Either
    1. use "ClassName::aliasedMethodName" in the "Title" column instead of the original name. Similar to 1) this could then either link to the API page of the original method after 2) has been resolved (preferred) or to a separate API page using the aliased method name that mentions that the method is an alias of TraitName::originalMethodName (not ideal, but might be easier to implement and better than nothing).
    2. use something like "TraitName::originalName as ClassName::aliasedMethodName in the title column to make it more obvious that this is an aliased method and keep the link to the API page for the original method. This might not be ideal for a11y reasons, though?
    3. Something else?

Remaining tasks

Make some decisions on the actual UI changes to implement, then provide an MR.

User interface changes

See proposed resolution.

API changes

tbd

Data model changes

tbd

✨ Feature request
Status

Active

Version

2.0

Component

User interface

Created by

🇩🇪Germany FeyP

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024