[DRAFT, WIP] PSR-5: PHPDoc Standard

[mvriel]

This PR represents the current state of affairs with the PHPDoc Standard. Until this description and subject is altered this PR is considered a Work in Progress and not ready for a final review.

All feedback is welcome, please direct this to the PHP-FIG mailing list to prevent noise in this PR. This PSR covers so many subjects that unless the discussions are separated by topic that it will probably be quite impossible to follow in this PR.

I would also request that people open a thread per issue they would like to discuss and not combine several issues in a single mail; this will help to keep noise-levels down in discussions and for me to loook back or filter important information.

TODO items are tracked in the issue tracker for this PSR: https://github.com/phpDocumentor/fig-standards/issues

[mnapoli]

Why are there two 8.?

I can't find "Describing anonymous functions" anywhere in the document.

[michaelcullum]

Are @access and @static not being added?

[mnapoli]

Why are there changes for PSR-4?

[mvriel]

Adding it as a new tag seems a bit much to me, mainly because it is more or less a specialisation for @link when purely considered from a reader's perspective. Perhaps it would better be served as a specialisation tag such as @link:prose tuts/someMethod.md although I must add that I would not recommend such usage.

A DocBlock's strength is that it sits close to the code that it documents and by referring to, for example, a tutorial you are possibly negating that strength since it is no longer purely about the method. This is a bit of a unit test versus integration test situation where the DocBlock itself is equal to a unit test in scope and a tutorial more of a integration test.

Also: by referencing an external location, especially a relative one, one will run a higher risk of referring to non-existing documentation

[shadowhand]

Is this implying that every single file in a project must have a file-level docblock?

[cebe]

Maybe add an , if present:

An exception to this principle is the File-level DocBlock which, if present, MUST be
placed at the top of a PHP source code file as the first DocBlock in a file.

[mlocati]

For non-static methods (implemented via __call()) we have
@method [return type] [name]([type] [parameter], [...]) [description]

What about static methods (implemented via __callStatic())?
My suggestion:
@method [static] [return type] [name]([type] [parameter], [...]) [description]

If otherwise static may already be part of return type, what about explaining in the docs that @method is useful to describe methods implemented via __call and via __callStatic?

[olvlvl]

@mlocati +1, I'm already using this with PhpStorm: https://github.com/ICanBoogie/ActiveRecord/blob/master/lib/ActiveRecord/Helpers.php#L17

Just a thought about @method, starting PHP7 the return type of a function may be defined as follows:

function foo(): array {
    return [];
}

Maybe @method could follow this, e.g. @method foo(): array. What do you think?

[mlocati]

Maybe @method could follow this, e.g. @method foo(): array. What do you think?

@olvlvl I'd prefer to keep the current approach, so that all the @<something> follow the same rule (type name)...

[olvlvl]

@mlocati Good point.

[ghost]

Regarding docblock inheritance for methods: are docblocks inherited from trait methods? For example, if class C uses trait T, where T defines method foo (with docblock) and C also defines foo (without docblock), does the foo from C inherit the docblock from T? In a certain way, traits are code that is injected into the class, so in essence the original trait method "disappears" from the equation as soon as it's redefined in the class itself, so would docblocks not be inherited in this case?

Similarly, if method foo in trait T does not specify a docblock and C now extends parent class P, which also defines a foo, does the foo from the trait also inherit documentation from the foo in P (and hence, can it use things such as {@inheritDoc} for this purpose)? Using the same logic as above, that would also be the case.

EDIT: I've made a ticket for this here [1], my apologies for disturbing the PR.

[1] phpDocumentor#128

[cebe]

@Gert-dev yes, traits should be considered in the way you described imo.

[ghost]

(Moved my post to a separate ticket here [1].)

[1] phpDocumentor#127

[mlocati]

I think that we should adopt the most restrictive approach.

Think for instance at this example:

/**
 * @param string $name
 */
function printName($name)
{
    if ($name === '') {
        echo 'You belong to the Anonymous team ;)';
    } else {
        echo "Your name is $name";
    }
}

[michaelcullum]

This should be merged anyway as proposed PSRs live in the main repo.