Merge pull request #1 from ashnazg/psr5

Trimming Verbiage for PSR Revival

Author: ashnazg

proposed/phpdoc-meta.md

@@ -2,31 +2,22 @@
 
 ## 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 was first presented in 2000 by Ulf Wendel, 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.
+PHPDocumentor has 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 a formal standard
+instead of its de-facto status.
 
 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.
 * 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.
+* Projects using the PHPDoc data to complement their functionality, such as Documentation generators or static
+  analysis tools, will have a common language with their consumers.
 
 Cons:
 

proposed/phpdoc-tags.md

@@ -690,10 +690,10 @@ function or method. When provided, it MUST contain a "Type"
 to indicate what is returned; the description on the other hand is OPTIONAL yet
 RECOMMENDED in case of complicated return structures, such as associative arrays.
 
-It is RECOMMENDED to use this tag with every function and method.
-If no `@return` type is given, and no return type declaration is provided in
-the code signature, an interpreter MUST interpret this as if `@return mixed`
-is provided.
+It is RECOMMENDED to use this tag with every function or method where PHP native
+types are insufficient.  If no `@return` type is given, and no return type
+declaration is provided in the code signature, an interpreter MUST interpret
+this as if `@return mixed` is provided.
 
 This tag MUST NOT occur more than once in a "DocBlock" and is limited to the
 "DocBlock" of a "Structural Element" of a method or function.