Skip to content
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
Merged
Changes from all commits
Commits
Show all changes
99 commits
Select commit Hold shift + click to select a range
796b9d9
Submit PHPDoc proposal and meta-document
mvriel Aug 5, 2013
1572a8b
textual changes from first pass review
ashnazg Aug 5, 2013
ad2a261
textual changes from second pass review
ashnazg Aug 5, 2013
853f44b
Merge pull request #1 from ashnazg/chuck-review
mvriel Aug 5, 2013
6d1451d
Added Donald Gilbert as sponsor for phpdoc
mvriel Aug 6, 2013
fc11367
Merge branch 'master' of github.com:phpDocumentor/fig-standards
mvriel Aug 6, 2013
27d90d3
Fix indenting issues
Seldaek Aug 13, 2013
e5097b4
Merge pull request #8 from Seldaek/patch
mvriel Aug 13, 2013
5c56bd9
Remove extraneous lines from null keyword example
joncave Aug 17, 2013
99dad5c
Don't use single type notation for mixed type arrays
joncave Aug 17, 2013
f8d5382
Merge pull request #11 from joncave/patch-1
mvriel Aug 17, 2013
cb518e8
Merge pull request #12 from joncave/patch-2
mvriel Aug 17, 2013
7b41a17
Fixing internal links to the tags
JDGrimes Aug 20, 2013
87623ec
#6: Add Generics notation description and refactor ABNF
mvriel Aug 20, 2013
2b4ff37
Merge branch 'master' of github.com:phpDocumentor/fig-standards
mvriel Aug 20, 2013
c640add
Merge pull request #13 from JDGrimes/patch-1
mvriel Aug 20, 2013
b3c9f8a
Merge branch 'master' of github.com:phpDocumentor/fig-standards
mvriel Aug 20, 2013
9b232fb
Update PSR number to PSR-5
mvriel Aug 29, 2013
761afeb
#16: Improve definition of DocComment and object
mvriel Sep 4, 2013
a7c09ca
#16: Update Type ABNF according to the suggestion of @nikic
mvriel Sep 4, 2013
1853628
Fix nested lists
GaryJones Sep 23, 2013
2d6149d
Fix typo
GaryJones Sep 23, 2013
dd20d56
Use File-Level, not Page-Level, for consistency
GaryJones Sep 24, 2013
8556da6
Update @return tag exceptions for constructors, fixes #18
Oct 10, 2013
9748de1
Merge branch 'master' of https://github.com/php-fig/fig-standards
mvriel Oct 11, 2013
a0f9141
Reword PSR-4 to be more verbose and complete
mvriel Oct 11, 2013
0e75d8a
Change indentation to MD format
mvriel Oct 11, 2013
b26791d
Fix numbering
mvriel Oct 11, 2013
ff1ae19
Merge pull request #31 from alexrussell/patch-1
mvriel Nov 1, 2013
1b68927
Merge pull request #29 from GaryJones/patch-5
mvriel Nov 1, 2013
f717b2b
Merge pull request #25 from GaryJones/patch-2
mvriel Nov 2, 2013
31d593c
Merge pull request #23 from GaryJones/patch-1
mvriel Nov 2, 2013
7b822dd
Fixes #34: altered special exception for @return
mvriel Nov 29, 2013
c54bc1f
#36 Addresses an ambiguous example
mvriel Nov 29, 2013
36e82be
Merge branch 'master' of https://github.com/php-fig/fig-standards
mvriel Dec 4, 2013
365d1a1
Removed meta-information as that is already, or should be, in the met…
mvriel Dec 4, 2013
1d6b650
Removed erroneous TOC entry
mvriel Dec 4, 2013
eac8337
Refactored the @type definition according to recent discussions
mvriel Dec 4, 2013
78c73ec
#36 Adjusted ABNF to allows line breaks in tag descriptions
mvriel Dec 4, 2013
0f90737
#36 Clarified the structure of a tag by describing the parts and that…
mvriel Dec 4, 2013
2e1b505
Fix typo
mvriel Dec 4, 2013
520e410
Clarify that @var is not as much an alias of @type
mvriel Dec 4, 2013
1df2582
#2 describe @see in more detail and add deprecation of @link
mvriel Dec 4, 2013
065e65b
Add markdown as requirement for tag descriptions
mvriel Dec 7, 2013
44519fd
Add markdown as requirement for tag descriptions
mvriel Dec 7, 2013
051d5f9
Merge branch 'master' of https://github.com/php-fig/fig-standards
mvriel Mar 25, 2014
8fe3d42
Introduced Summary
mvriel Mar 25, 2014
db15c21
Fixes #3: Add Inline PHPDoc description
mvriel Mar 25, 2014
cbf58ef
consolidate the two FQSEN definitions;
ashnazg Mar 29, 2014
ed9e863
'annotation' is a defined term, so use 'name' here;
ashnazg Mar 29, 2014
a3dacae
Change meaning of @deprecated version and add a second machine-readab…
sun May 18, 2014
f001ebe
Specify @deprecated versions as a range, delimited by a colon.
sun May 20, 2014
4319c6c
Merge pull request #46 from ashnazg/nameNotAnnotation
mvriel May 24, 2014
68bc885
Merge pull request #45 from ashnazg/dupeFQSEN
mvriel May 24, 2014
604e15c
Revised @deprecated tag description using explicit 'starting version'…
sun May 24, 2014
8e272d4
Revised @deprecated to clarify that the stated 'ending version' is ex…
sun May 24, 2014
f9fccfa
Added description and some discussion on tag specializations
choult May 29, 2014
adc0241
Improved layout of tag specialization docs
choult May 29, 2014
d44d6c7
Merge pull request #51 from chrishoult/feature/tag-specialization-docs
mvriel Jun 6, 2014
40f9b13
Fixed synposis + description of `@license`.
sun Jun 6, 2014
1d07566
Add typedef tag
mvriel Jul 15, 2014
61c695c
Reverted @type to @var and changed compound @var notation to match PHPs
mvriel Aug 8, 2014
a015038
Fixed chapter numbering
mvriel Aug 8, 2014
1d20343
Added a text explaining how to recognize the File-level DocBlock
mvriel Aug 15, 2014
4f4b640
Clarified the paragraph on File-level DocBlocks
mvriel Aug 15, 2014
8a6a2ff
Clean-up of all external hyperlinks.
Fleshgrinder Nov 23, 2014
ca1477e
Be more specific about static in PHPDoc vs. PHP
Fleshgrinder Nov 23, 2014
30fdbb2
Formatting
Fleshgrinder Nov 23, 2014
4f588d7
Merge branch 'master' of https://github.com/php-fig/fig-standards
mvriel Dec 9, 2014
5317d4f
Merge pull request #50 from sun/psr5-deprecated
mvriel Dec 9, 2014
eda5e92
Merge pull request #52 from sun/license
mvriel Dec 9, 2014
0633623
Post-process @license edit
mvriel Dec 9, 2014
143e8d8
Merge pull request #54 from phpDocumentor/features/typedef
mvriel Dec 9, 2014
a63e95f
Merge pull request #55 from phpDocumentor/features/type-to-var
mvriel Dec 9, 2014
04b3e73
Merge pull request #66 from Fleshgrinder/master
mvriel Dec 9, 2014
f650a15
Add paragraph with summary to clearly indicate no explicit recommenda…
mvriel Dec 9, 2014
6861e37
#68: Add clause that an empty line is allowed between a DocBlock and …
mvriel Dec 17, 2014
46e4e4e
phpdoc.md - make TOC clickable
Feb 19, 2015
b3f503f
Merge pull request #70 from TomasVotruba/patch-1
mvriel Mar 3, 2015
e287633
Remove Style recommendation
mvriel Mar 4, 2015
0379e00
Fix small typo in @since example
Mar 6, 2015
5f209f9
Fixed scalar types
GrahamCampbell Mar 25, 2015
38222fe
"is it NOT" to "it is NOT"
Rarst Mar 25, 2015
b293909
Merge pull request #74 from Rarst/patch-1
mvriel Mar 26, 2015
5b68085
Merge pull request #73 from GrahamCampbell/patch-1
mvriel Mar 26, 2015
d6b9e48
Fixed an unclosed docblock
GrahamCampbell Mar 26, 2015
eca33f8
Fixed a typo
GrahamCampbell Mar 26, 2015
2726c89
Merge pull request #75 from GrahamForks/patch-1
mvriel Mar 26, 2015
d486bad
fix @version example
Netmosfera May 2, 2015
b55176c
Merge branch 'master' of git://github.com/php-fig/fig-standards
mvriel Jun 5, 2015
63af227
Update phpdoc.md
gerardroche Jul 20, 2015
da00906
Merge pull request #71 from nueckman/patch-1
mvriel Aug 14, 2015
d27159e
Merge pull request #78 from WesNetmo/master
mvriel Aug 14, 2015
8abaef4
Merge pull request #84 from gerardroche/patch-1
mvriel Aug 14, 2015
e8ae204
Merge branch 'master' of git://github.com/php-fig/fig-standards
mvriel Aug 14, 2015
695b38a
Merge branch 'master' of github.com:phpDocumentor/fig-standards
mvriel Aug 14, 2015
3b425d1
Removed contentious sections and other various updates
mvriel Dec 10, 2015
ead19fb
Fix typo in table of contents
spiegelm Feb 24, 2016
b994d85
Merge pull request #126 from spiegelm/patch-1
mvriel Feb 26, 2016
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.
+2,246 −0
Diff settings

Always

Just for now

@@ -0,0 +1,117 @@
PHPDoc Meta Document
====================

1. Summary
----------

The purpose of documentation using PHPDoc is to provide a comprehensive but flexible way to describe a software system
at the smallest possible level of detail. This type of documentation aids contributors and consumers of your source
code to, for example, understand what type of information needs to be passed to specific methods, or how to be able to
consume a class of the project that a consumer want to use.

By documenting specific elements inside the source code the documentation for that part of the source code will be less
susceptible to becoming out of date.

PHPDoc as a notation has existed for more than ten years now, is heavily inspired by JavaDoc, and is currently in use by a
significant percentage of public PHP projects in the field.

2. Why Bother?
--------------

PHPDocumentor has spearheaded and facilitated the growth of the PHPDoc notation, but with the growing number of other
tools that use the PHPDoc notation, it is becoming increasingly important to have an official and formal standard
instead of the de-facto status that is currently provided.

An additional goal for this PSR is to deprecate obsolete elements and introduce new concepts and syntaxes to reflect the
current status of the PHP language, and to facilitate best practices and design patterns in use today and in the
foreseeable future.

Pros:

* Developers (consumers) have a common reference to refer to when confronted with PHPDoc.
* Projects and their Developers (contributors) have an authoritative reference which they can consult.

This comment has been minimized.

Copy link
@jhodgdon-drp

jhodgdon-drp Jul 10, 2014

Grammar: which -> that in this line

* IDE vendors can standardize the way they use PHPDoc to aid in concerns such as auto-completion and navigation.
* Projects using the PHPDoc data to complement their functionality, such as Documentation generators or applications
using annotations, will have a common language with their consumers.
* Missing functionality can be described and implemented by aforementioned stakeholders.

Cons:

* If there are different uses of elements in the PHPDoc notation, then it is desirable for projects to align with this
specification, which will cost effort to introduce.
* Deprecation of well-known PHPDoc elements may lead to a period of confusion or resistance to the proposed changes. It
is for this reason that concepts are deprecated and not removed.
* Given the age of the current standard and widespread adoption, it is not possible to introduce significant breaks in
backwards compatibility with the current practices without a significant risk of alienating existing users or vendors.

3. Scope
--------

## 3.1 Goals

* Provide a complete technical definition, or schema, of the PHPDoc notation.
* Introduce new concepts matching best practices or design patterns in use today and in the foreseeable future.
* Deprecate old concepts that are replaced by newer concepts or are no longer in use in today's PHP landscape.

## 3.2 Non-Goals

* This PSR does not provide a recommendation on how and when to use the concepts described in this document,
so it is not a coding standard.

This comment has been minimized.

Copy link
@jhodgdon-drp

jhodgdon-drp Jul 10, 2014

However, at least one place in this document (@return section), it says what individual projects can and can't do in their coding standards, so I think this statement is kind of misleading?

This comment has been minimized.

Copy link
@mvriel

mvriel Jul 10, 2014

Author Contributor

At best the statement in the @return section can be improved upon; that statement underlines that Coding Standards are free to do something. If you encounter any other statements that you consider not in line with this non-goal then please inform us so.

'This Standard is not a Coding Standard but a Technical description of a DSL' is one of the most important goals for this document.

* This PSR facilitates the creation of annotations by allowing the notation needed for Symfony/Doctrine style
annotations, but does not describe a style of annotations or which "defined annotations" exist in use. The concept of annotations is only
alluded to and is out of scope for this PSR.

4. Approaches
-------------

### 4.1 Chosen Approach

We have decided to formalize the existing practices, observe non-documented usages (such as Doctrine-style
annotations), and observe feature requests with Documentation generators (such as phpDocumentor).

The combination of these should be described in sufficient detail as to reduce the amount of possible interpretation.

In addition to the above, the authors have taken care to provide for future expansions and tag additions that do not
affect the Syntax of PHPDoc itself.

Pros:

* Delivers a machine-parsable and verifyable specification.
* Well-rounded proposal due to the number of factors considered.

Cons:

* Technical and verbose.
* Can only be extended when the syntax is not affected.

5. People
---------

### 5.1 Editor(s)

* Mike van Riel

### 5.2 Sponsors

* Phil Sturgeon
* Donald Gilbert

### 5.3 Contributors

* Chuck Burgess
* Gary Jones

6. Votes
--------

* **Entrance Vote: ** TBD
* **Acceptance Vote:** TBD

7. Relevant Links
-----------------

Most of the relevant links are mentioned in the PSR itself as support for individual chapters.

_**Note:** Order descending chronologically._

* [Original draft](https://github.com/phpDocumentor/phpDocumentor2/commit/0dbdbfa318d197279b414e5c0d1ffb142b31a528#docs/PSR.md)
Oops, something went wrong.
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.