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
Commits
Jump to file or symbol
Failed to load files and symbols.
+2,246 −0
Diff settings

Always

Just for now

View
@@ -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.

@jhodgdon-drp

jhodgdon-drp Jul 10, 2014

Grammar: which -> that in this line

@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.

@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?

@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.

@mvriel

mvriel Jul 10, 2014

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.

@mvriel

mvriel Jul 10, 2014

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.