rfc:docblockparser
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
rfc:docblockparser [2010/09/16 00:06] – created cfulton | rfc:docblockparser [2017/09/22 13:28] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 3: | Line 3: | ||
* Date: 2008-03-06 | * Date: 2008-03-06 | ||
* Author: Chad Fulton < | * Author: Chad Fulton < | ||
- | * Status: | + | * Status: |
* First Published at: http:// | * First Published at: http:// | ||
Line 16: | Line 16: | ||
* **Type Information** - Since PHP is a loosely typed language, there is currently no venue for encoding expected type information for use in, e.g. validation or sanitization routines. | * **Type Information** - Since PHP is a loosely typed language, there is currently no venue for encoding expected type information for use in, e.g. validation or sanitization routines. | ||
* **Relationships** - In an application with many model-type classes, there almost always exist many relationships between the models that go beyond the parent-child one modeled by class inheritance. For example, the " | * **Relationships** - In an application with many model-type classes, there almost always exist many relationships between the models that go beyond the parent-child one modeled by class inheritance. For example, the " | ||
- | * **Other** - Unfortunately, | + | * **Other** - Most of the use cases fall into the " |
For other use cases, see also [[http:// | For other use cases, see also [[http:// | ||
- | ==== Why should | + | ==== Why should this functionality be in php core? ==== |
- | 1. There is already a widely used syntax for structured DocBlocks (short description, | + | - There is already a widely used syntax for structured DocBlocks (short description, |
- | 2. For metadata | + | - As many of the use cases involve frameworks or other software intended |
+ | - The Reflection extension already in core is a natural place to put this as a complement to getDocComment(). | ||
===== Common Misconceptions ===== | ===== Common Misconceptions ===== | ||
- | RFCs do not in any way replace discussions on the mailing list. | + | **Comments should |
+ | |||
+ | There is no doubt that in general, commenting code means that it should be ignored by the parser. Despite this, I think there is reason to support parsing docBlocks. | ||
+ | |||
+ | First of all, not all comments become docBlocks. They must precede a structure (class, function, property, method), and they must have the <code php>/** ... */</ | ||
+ | |||
+ | <code php> | ||
+ | // | ||
+ | # | ||
+ | /* ... */ | ||
+ | </ | ||
+ | are NOT docBlocks. | ||
+ | |||
+ | Therefore, the comments that could potentially effect runtime behavior are isolated to a very specific set. Also, popular convention for docBlocks that already exists will support understanding of this difference. | ||
+ | |||
+ | Furthermore, | ||
===== Proposal ===== | ===== Proposal ===== | ||
- | Nothing needs to be patched here. Just use this template at your discretion. | + | This proposal is for a function which parses docBlocks and returns an associative array with text key=> |
+ | * ReflectionClass:: | ||
+ | * ReflectionFunctionAbstract:: | ||
+ | * ReflectionProperty:: | ||
- | ==== Rejected Features ==== | + | This proposal suggests that whitespace be treated similarly to in HTML (all whitespace gets reduced to a single space character) except that empty lines are significant (see example 1 below for explanation of this rule). |
- | Automated voting system. | + | === Draft EBNF for docBlock parsing: === |
- | ==== More about RFCs ==== | + | < |
+ | docblock | ||
+ | short_description := line , { emptyline }+ ; | ||
+ | long_description | ||
+ | line := [space] , "* " , [space] , character-" | ||
+ | emptyline | ||
+ | tag := [space] , "* " , " | ||
+ | ignored | ||
+ | string | ||
+ | tagname | ||
+ | space := " " | " | ||
+ | linebreak | ||
+ | character | ||
+ | </ | ||
- | http:// | + | === Examples === |
- | ===== Changelog ===== | + | == 1. The following shows a docBlock being parsed via this function: |
+ | <code php> | ||
+ | /** | ||
+ | * (Short Description) | ||
+ | * | ||
+ | * (Long Description ... | ||
+ | | ||
+ | * long description continues... | ||
+ | * | ||
+ | * | ||
+ | * | ||
+ | * still long description ...) | ||
+ | | ||
+ | * @tag1 this is some text for tag1 | ||
+ | * @tag2 | ||
+ | * | ||
+ | * @tag3 this is some | ||
+ | | ||
+ | | ||
+ | | ||
+ | * | ||
+ | * (After tags begin, any text which has an empty line | ||
+ | * between it and the preceding tag will be completely | ||
+ | * ignored) | ||
+ | * | ||
+ | * @tag4 this is some | ||
+ | * non-pretty-indented | ||
+ | * multiline text | ||
+ | * for tag 4 | ||
+ | * | ||
+ | * (as above, this is ignored) | ||
+ | */ | ||
+ | class foo { | ||
+ | // ... | ||
+ | } | ||
+ | |||
+ | $r = new ReflectionClass(' | ||
+ | var_dump($r-> | ||
+ | |||
+ | /* | ||
+ | array(3) { | ||
+ | [" | ||
+ | string(19) " | ||
+ | [" | ||
+ | string(85) "(Long Description ... | ||
+ | |||
+ | long description continues... | ||
+ | |||
+ | |||
+ | |||
+ | still long description ...)" | ||
+ | [" | ||
+ | array(4) { | ||
+ | [" | ||
+ | string(26) "this is some text for tag1" | ||
+ | [" | ||
+ | string(0) "" | ||
+ | [" | ||
+ | string(53) "this is some pretty-indented multiline text for tag3" | ||
+ | [" | ||
+ | string(58) "this is some non-pretty-indented multiline text for tag 4" | ||
+ | } | ||
+ | } | ||
+ | */ | ||
+ | |||
+ | </ | ||
+ | |||
+ | == 2. The following shows examples of docblocks that could not be parsed: == | ||
+ | |||
+ | <code php> | ||
+ | |||
+ | /** | ||
+ | * This looks like a docblock, but since it doesn' | ||
+ | * precede a structure, it's not. | ||
+ | */ | ||
+ | |||
+ | // This is a comment ... but not a docblock | ||
+ | class foo() { | ||
+ | } | ||
+ | |||
+ | # This is a comment ... but not a docblock | ||
+ | class bar() { | ||
+ | } | ||
+ | |||
+ | /* | ||
+ | * This looks a lot like a docblock, but it's not one | ||
+ | * because it's opening line does not have two *. | ||
+ | * | ||
+ | * @tag this tag couldn' | ||
+ | */ | ||
+ | class baz() { | ||
+ | } | ||
+ | |||
+ | function foobar() { | ||
+ | /** | ||
+ | * This looks like a docblock, but since it doesn' | ||
+ | * precede a structure, it's not. | ||
+ | */ | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | === What is a docblock: === | ||
+ | A comment block using /** ... */ syntax, preceding a class, function, property, or method. This is the same as is currently used for the getDocComment() function in Reflection. | ||
+ | |||
+ | === What will not happen: === | ||
+ | * Nothing will be done automatically - the getParsedDocComment() function must be called first. | ||
+ | * No comment block except for the docblocks described above will be available for parsing. | ||
+ | * At no point will anything in docBlocks be executed by the PHP engine. | ||
+ | |||
+ | ==== Rejected Features ==== | ||
+ | |||
+ | TBD? | ||
+ | |||
+ | ==== BC Breaks ==== | ||
+ | |||
+ | None. | ||
+ | ===== Changelog ===== | ||
+ | 2010-09-16 cfulton Initial RFC creation. |
rfc/docblockparser.1284595610.txt.gz · Last modified: 2017/09/22 13:28 (external edit)