New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DRAFT, WIP] PSR-5: PHPDoc Standard #169

Merged
merged 99 commits into from Jul 9, 2016

Conversation

Projects
None yet
@mvriel
Copy link
Contributor

mvriel commented Aug 28, 2013

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

mvriel and others added some commits Aug 5, 2013

Submit PHPDoc proposal and meta-document
See phpDocumentor/phpDocumentor2@0dbdbfa#docs/PSR.md
for the original draft written by the same editor and contributors. This is a continuation of that
version (hence the deeplink since the document will be removed from the repository).
Merge pull request #11 from joncave/patch-1
Remove extraneous lines from null keyword example
Merge pull request #12 from joncave/patch-2
Don't use single type notation for mixed type arrays
Fixing internal links to the tags
Fixing links to the Tags, which has been moved from section 7, and is now section 8. Also fixing @uses to be 8.23 instead of a second 8.22. (I also noticed there is a missing section that is in the index "Describing anonymous functions", but I didn't touch that).
Merge pull request #13 from JDGrimes/patch-1
Fixing internal links to the tags
#16: Update Type ABNF according to the suggestion of @nikic
@nikic has pointed out several shortcomings to the ABNF for types, his suggestion
is a solid improvement to the BNF and has been used. One modification has been made;
the 1*SP in the generic definition has been replaced with *SP to allow zero spaces as well.
Fix nested lists
Markdown wasn't seeing the unordered list as nested, so the list items were appearing as:

1.
*
*
*
1.

It now appears correctly as:

1.
  *
  *
  *
2.
Use File-Level, not Page-Level, for consistency
There are several mentions of "File-Level" throughout the documentation, but one inconsistent reference to the previous term of "Page-Level".
Update @return tag exceptions for constructors, fixes #18
Constructors should assume `@return $this` rather than `@return self` as per discussion in bug #18
6.3. Constant Or Property
7. Describing hashes
8. Describing anonymous functions
8. Tags

This comment has been minimized.

@mnapoli

mnapoli Oct 21, 2013

Member

Why are there two 8.?

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

This comment has been minimized.

@michaelcullum

michaelcullum Oct 29, 2013

Member

Are @access and @static not being added?

@mnapoli

This comment has been minimized.

Copy link
Member

mnapoli commented Oct 23, 2013

Why are there changes for PSR-4?

@mvriel

This comment has been minimized.

Copy link
Contributor

mvriel commented Aug 6, 2015

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

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

This comment has been minimized.

@shadowhand

shadowhand Sep 7, 2015

Contributor

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

This comment has been minimized.

@cebe

cebe Sep 8, 2015

Contributor

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.

@ghost ghost referenced this pull request Sep 10, 2015

Closed

Add support for {@inheritdoc} #86

@mlocati

This comment has been minimized.

Copy link

mlocati commented Oct 27, 2015

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

This comment has been minimized.

Copy link

olvlvl commented Oct 27, 2015

@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

This comment has been minimized.

Copy link

mlocati commented Oct 27, 2015

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

This comment has been minimized.

Copy link

olvlvl commented Oct 27, 2015

@mlocati Good point.

@ghost

This comment has been minimized.

Copy link

ghost commented Mar 3, 2016

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

This comment has been minimized.

Copy link
Contributor

cebe commented Mar 3, 2016

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

@ghost

This comment has been minimized.

Copy link

ghost commented Mar 9, 2016

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

[1] phpDocumentor#127

@mlocati

This comment has been minimized.

Copy link

mlocati commented Mar 10, 2016

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 comment has been minimized.

Copy link
Member

michaelcullum commented Jul 9, 2016

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

@michaelcullum michaelcullum merged commit a82e13e into php-fig:master Jul 9, 2016

ashnazg added a commit to ashnazg/fig-standards that referenced this pull request Oct 14, 2018

Merge pull request php-fig#169 from ashnazg/callable
callable is no longer pseudo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment