Skip to content

Chuck's review #1

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Aug 5, 2013
Merged

Chuck's review #1

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1572a8b
textual changes from first pass review
ashnazg Aug 5, 2013
ad2a261
textual changes from second pass review
ashnazg Aug 5, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions proposed/phpdoc-meta.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,23 @@ PHPDoc Meta Document

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
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 will the documentation for that part of the source code be less
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 exists for more than ten years now, is heavily inspired by JavaDoc and currently in use by a
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
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 syntax to reflect the
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.

Expand All @@ -37,11 +37,11 @@ Pros:

Cons:

* If there are different uses of elements in the PHPDoc notation then it is desirable for projects to align with this
* 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
* 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
* 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
Expand All @@ -55,23 +55,23 @@ Cons:

## 3.2 Non-Goals

* This PSR does not provide a recommendation on how and when to use the concepts described in this document;
not a coding standard.
* 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 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 there are. The concept of annotations is only
alluded at and out of scope for this PSR.
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.
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
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:
Expand Down