Skip to content

Commit ed27869

Browse files
committed
Trim down the non-spec verbiage.
1 parent 468721f commit ed27869

File tree

1 file changed

+5
-14
lines changed

1 file changed

+5
-14
lines changed

proposed/phpdoc-meta.md

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,22 @@
22

33
## 1. Summary
44

5-
The purpose of documentation using PHPDoc is to provide a comprehensive but flexible way to describe a software system
6-
at the smallest possible level of detail. This type of documentation aids contributors and consumers of your source
7-
code to, for example, understand what type of information needs to be passed to specific methods, or how to be able to
8-
consume a class of the project that a consumer want to use.
9-
10-
By documenting specific elements inside the source code, the documentation for that part of the source code will be less
11-
susceptible to becoming out of date.
12-
135
PHPDoc as a notation was first presented in 2000 by Ulf Wendel, is heavily inspired by JavaDoc,
146
and is currently in use by a significant percentage of public PHP projects in the field.
157

168
## 2. Why Bother?
179

18-
PHPDocumentor has spearheaded and facilitated the growth of the PHPDoc notation, but with the growing number of other
19-
tools that use the PHPDoc notation, it is becoming increasingly important to have an official and formal standard
20-
instead of the de-facto status that is currently provided.
10+
PHPDocumentor has facilitated the growth of the PHPDoc notation, but with the growing number of other
11+
tools that use the PHPDoc notation, it is becoming increasingly important to have a formal standard
12+
instead of its de-facto status.
2113

2214
Pros:
2315

2416
* Developers (consumers) have a common reference to refer to when confronted with PHPDoc.
2517
* Projects and their Developers (contributors) have an authoritative reference which they can consult.
2618
* IDE vendors can standardize the way they use PHPDoc to aid in concerns such as auto-completion and navigation.
27-
* Projects using the PHPDoc data to complement their functionality, such as Documentation generators or applications
28-
using annotations, will have a common language with their consumers.
29-
* Missing functionality can be described and implemented by aforementioned stakeholders.
19+
* Projects using the PHPDoc data to complement their functionality, such as Documentation generators or static
20+
analysis tools, will have a common language with their consumers.
3021

3122
Cons:
3223

0 commit comments

Comments
 (0)