PHPDoc Extension: @alias

NOTE: This tag is proposed as an extension to the PHPDoc PSR. As an extension, this document inherits all sections of the PHPDoc PSR including conventions, definitions, principles, and other patterns.

Summary

The @alias tag provides a way to document methods which are nothing more than aliases of other methods.

While @see could be used for a similar purpose, having a more specific annotation allows us to handle aliases (i.e., exact duplicates) differently than structures that are simply related or similar.

For existing usage, see implode() and its alias join().

Syntax

@alias <method()>

Description

With the @alias tag, it is possible to document a method as being an exact duplicate of another function or method. When provided:

1. It MUST refer to a method or function. That method MUST be contained in the same scope (Class for methods, Namespace for functions).
2. It MUST NOT point to a method which is an alias itself (i.e., uni-directional, NOT circular, NOT chained).
3. It MAY include open-close parens at the end of the method name (OPTIONAL yet RECOMMENDED).
4. It MAY be used in conjunction with @deprecated as appropriate.

Examples

class Example
{
    function stringStartsWith($subject, $string) { /* code */ }

    /**
     * @alias stringStartsWith()
     */
    function prefixOf($subject, $prefix) { /* code */ }
}