[VOTE][Entrance]: PHPDoc Standard

2,478 views
Skip to first unread message

Phil Sturgeon

unread,
Aug 13, 2013, 9:39:37 AM8/13/13
to php...@googlegroups.com
The phpDocumentor team have for a while been working on a standard for PHPDoc / DocBlock tags and definitions. 

This vote is not to make it an "Accepted" PSR, and you don't need to agree with all of the wording. This vote is only to move the PHPDoc standard from Pre-Draft to Draft. 

If you like the idea in general, but have feedback on wording, formatting, code examples, whatever, then vote yes and send a pull request to the phpDocumentor fork now or later.

Editor: Mike van Riel
Sponsors: Phil Sturgeon (Co-ordinator) & Donald Gilbert

This vote will come to a close August 27th at 17:00 EST.

As Coordinator I am still allowed to vote on behalf of my project, so:

+1 from PyroCMS

P.S: I am currently a coordinator for two proposals at the same time, which is going to be a chunk of work. I'm not trying to get involved with every PSR ever, I am just very interested in these two. I wont take on any more until these are accepted.

Drak

unread,
Aug 13, 2013, 9:41:41 AM8/13/13
to php...@googlegroups.com
+1 from Zikula.


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/60613603-1080-4078-b103-1dc2b232fedc%40googlegroups.com?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

John Mertic

unread,
Aug 13, 2013, 9:43:22 AM8/13/13
to php...@googlegroups.com
+1 from SugarCRM

On 8/13/13, Drak <dr...@zikula.org> wrote:
> +1 from Zikula.
>
>
> On 13 August 2013 14:39, Phil Sturgeon <em...@philsturgeon.co.uk> wrote:
>
>> The phpDocumentor team have for a while been working on a standard for
>> PHPDoc / DocBlock tags and definitions.
>>
>> Pre-Draft
>> Document<https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md>
>> Meta
>> Document<https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc-meta.md>
>> This vote is not to make it an "Accepted" PSR, and you don't need to
>> agree with all of the wording. This vote is only to move the PHPDoc
>> standard from Pre-Draft to Draft.
>>
>> If you like the idea in general, but have feedback on wording,
>> formatting,
>> code examples, whatever, then vote yes and send a pull request to the
>> phpDocumentor fork now or later.
>>
>> *Editor: *Mike van Riel
>> *Sponsors:* Phil Sturgeon (Co-ordinator) & Donald Gilbert
>>
>> This vote will come to a close August 27th at 17:00 EST.
>>
>> As Coordinator I am still allowed to vote on behalf of my project, so:
>>
>> *+1 from PyroCMS*
>> *
>> *
>> *P.S: I am currently a coordinator for two proposals at the same time,
>> which is going to be a chunk of work. I'm not trying to get involved with
>> every PSR ever, I am just very interested in these two. I wont take on
>> any
>> more until these are accepted.*
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "PHP Framework Interoperability Group" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to php-fig+u...@googlegroups.com.
>> To post to this group, send email to php...@googlegroups.com.
>> To view this discussion on the web visit
>> https://groups.google.com/d/msgid/php-fig/60613603-1080-4078-b103-1dc2b232fedc%40googlegroups.com?hl=en
>> .
>> For more options, visit https://groups.google.com/groups/opt_out.
>>
>
> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/php-fig/CANAnSg3ftjK7KPF8noJokNVhxd%3Du7TaYU9T3yF-DS%3Dn%2B%2BfqMfw%40mail.gmail.com?hl=en.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
>


--
John Mertic
jme...@gmail.com | http://jmertic.wordpress.com

Cal Evans

unread,
Aug 13, 2013, 9:53:47 AM8/13/13
to php...@googlegroups.com
+1 from Community

=C=


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/60613603-1080-4078-b103-1dc2b232fedc%40googlegroups.com?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.



--
Read this book before you hire a 
developer to build your website.

Pádraic Brady

unread,
Aug 13, 2013, 10:01:34 AM8/13/13
to php...@googlegroups.com
Zend Framework votes +1.

Paddy

--
Pádraic Brady

http://blog.astrumfutura.com
http://www.survivethedeepend.com
Zend Framework Community Review Team
Zend Framework PHP-FIG Representative

Mike van Riel

unread,
Aug 13, 2013, 10:04:07 AM8/13/13
to php...@googlegroups.com
I am not really sure whether an editor may vote, if not please ignore this.

If so: +1 from phpDocumentor

Evert Pot

unread,
Aug 13, 2013, 10:04:35 AM8/13/13
to php...@googlegroups.com
+1 from me
> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CALwr1Gkc61t3EAN7NMSUov2fZrVX78LV95xWPP%3DedOKv3H7GDA%40mail.gmail.com?hl=en.

Donald Gilbert

unread,
Aug 13, 2013, 10:46:17 AM8/13/13
to php...@googlegroups.com
+1 from Joomla

Pádraic Brady

unread,
Aug 13, 2013, 11:01:04 AM8/13/13
to php...@googlegroups.com
If an Editor is a voting member, then their vote is as valid as anyone elses AFAIK.

Paddy


On 13 August 2013 15:46, Donald Gilbert <dilber...@gmail.com> wrote:
+1 from Joomla

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.
 
 



--

Jordi Boggiano

unread,
Aug 13, 2013, 11:42:02 AM8/13/13
to php...@googlegroups.com
+1

--
Jordi Boggiano
@seldaek - http://nelm.io/jordi

Brett Bieber

unread,
Aug 13, 2013, 12:44:33 PM8/13/13
to php...@googlegroups.com
+1


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.



--
Brett Bieber

Paul M. Jones

unread,
Aug 13, 2013, 1:25:40 PM8/13/13
to php...@googlegroups.com
+1 from Solar/Aura/etc


--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com


Fabien Potencier

unread,
Aug 13, 2013, 4:04:29 PM8/13/13
to php...@googlegroups.com
+1

Dowling, Michael

unread,
Aug 13, 2013, 4:05:02 PM8/13/13
to php...@googlegroups.com
+1 from AWS


William Durand

unread,
Aug 13, 2013, 4:04:54 PM8/13/13
to php...@googlegroups.com
+1

--
William Durand | http://www.williamdurand.fr


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

Taylor Otwell

unread,
Aug 14, 2013, 11:39:03 AM8/14/13
to php...@googlegroups.com
+1 From Laravel

guilher...@gmail.com

unread,
Aug 16, 2013, 12:53:55 AM8/16/13
to php...@googlegroups.com
-1

Reasons:
1- Tag names are broken according to ABNF. Examples:
@foo\
@test-\0

2- Tag names should support the same identifier format as PHP itself. That means:
tag-name = identifier *("\" identifier)
identifier = (ALPHA / "_") *(ALPHA / DIGIT / "_")

3- Certain libraries also support ":" for aliasing. Namespace alias would mean fallback of N namespaces to a single alias resolution

4- There is no @override tag in the spec

5- There's no plan to coexist with possible annotation drivers, such as Addendum and Doctrine. It is mentioned, but there's no real plan to avoid each other to be consider as the alternate.

6- No way to specify a Collection (read as ArrayAccess implementor) and also specify the element type it holds. Alternate example that would fix it:
@param Map<Application\Entity\User>

7- List are still fragile to be declared. Since we deprecate @subpackage, I may want to display the list of packages a given class is related to:
@package {"Application", "Application\Entity"}
Which could also take advantage of 5.4 format:
@package ["Application", "Application\Entity"]


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.
 
 



--
Guilherme Blanco
MSN: guilher...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Mike van Riel

unread,
Aug 16, 2013, 3:57:13 AM8/16/13
to php...@googlegroups.com
Hey Guilherme,

Thank you for providing feedback.

I find it somewhat odd that you vote -1 based on the contents of the document
as this is the entrance vote. Which is intended to poll interest for the subject of
the PSR independent of its contents.

After acceptance the document will be in draft status, where the Editor will
write or complete the PSR.

Having said that, I will elaborate on you feedback inline with your e-mail. Please
note that I refer to the issue tracker or this PSR often because I do not want to
flood this mailing list with long discussions on specific parts of the spec.

Using the github issue tracker will help keep the noise down on this list and have
a structured process where I can keep track of all comments. (also, please
only address 1 item per issue; this will help keep track of the work necessary)


On 08/16/2013 06:53 AM, guilher...@gmail.com wrote:
1- Tag names are broken according to ABNF. Examples:
@foo\
@test-\0
I agree; the last character should be ALPHA or DIGIT and not the wide range and
special characters should only be preceeded and succeeded by a ALPHA or DIGIT.
I have created the following issue to address this:
https://github.com/phpDocumentor/fig-standards/issues/10

2- Tag names should support the same identifier format as PHP itself. That means:
tag-name = identifier *("\" identifier)
identifier = (ALPHA / "_") *(ALPHA / DIGIT / "_")
This is the original limitation but prevents the notation used by Doctrine and excludes
existing tags with a hyphen (and I see no breaking issues that would mean to not
include a hyphen).

See point 5 for more information.


3- Certain libraries also support ":" for aliasing. Namespace alias would mean fallback of N namespaces to a single alias resolution
Can you open a suggestion at https://github.com/phpDocumentor/fig-standards/issues with more details and an
example of this behaviour?
I have not seen this being used. In addition; the spec mentions that the aliases defined with use statements in a file
are to be honoured; is this really an addition or an alternative for honouring use statements?



4- There is no @override tag in the spec
I do not know why you'd think a tag called @override should be in the spec. It has
never been a part of the PHPDoc nor has it been in use as far as I can gather.
If you believe a new tag called @override should be included in the specification,
please open an issue at https://github.com/phpDocumentor/fig-standards/issues
with details on what you expect it would do.

If you intend to include a tag similar to the Java @override annotation; please
know that this is not within scope of the PHPDoc Standard as that acts as a
compiler directive and not a documentation element.


5- There's no plan to coexist with possible annotation drivers, such as Addendum and Doctrine. It is mentioned, but there's no real plan to avoid each other to be consider as the alternate.
The PHPDoc Standard is designed to be _inclusive_ of annotation drivers. I have designed
the ABNF to support the notation of existing annotation drivers so that their tags are
considered legal according to this spec. This will enable tools to correctly interpret and
accept annotations in a PHPDoc section.

Thus: PHPDoc is not meant to be an alternate but an encompassing standard. As I see it,
the annotation notation is a subset of PHPDoc and not an alternative.

Having said that: PHPDoc intentionally does not provide a semantic meaning to the
different tag name notations. This is the responsibility of the individual Annotation drivers
or a future Annotations PSR.


6- No way to specify a Collection (read as ArrayAccess implementor) and also specify the element type it holds. Alternate example that would fix it:
@param Map<Application\Entity\User>

7- List are still fragile to be declared. Since we deprecate @subpackage, I may want to display the list of packages a given class is related to:
@package {"Application", "Application\Entity"}
Which could also take advantage of 5.4 format:
@package ["Application", "Application\Entity"]
A class or file is only related to one Category\Package\Subpackage combination; if you
want to suggest allowing classes and files to be tagged with multiple terms to identify
a class then please open a new issue in the issue tracker so that we can discuss this.

There recently has been a discussion on the phpDocumentor2 issue tracker where it
was suggested to repurpose @category to be able to place a class into several
categories. You can find more details here:
https://github.com/phpDocumentor/phpDocumentor2/issues/758

Karsten Dambekalns

unread,
Aug 16, 2013, 4:24:11 AM8/16/13
to php...@googlegroups.com
Hi.
> This vote is not to make it an "Accepted" PSR, and you don't need
> to agree with all of the wording. This vote is only to move the
> PHPDoc standard from Pre-Draft to Draft.

+1 from TYPO3 Flow.

Regards,
Karsten

Michael C

unread,
Aug 16, 2013, 6:32:25 AM8/16/13
to php...@googlegroups.com

Indeed. The entrance vote is about the meta-document and the concept of the PSR.

 

If it has been initially drafted, as it has in all three current entrance votes, it shouldn’t affect your vote as that is not what you are voting for.

 

Thanks,

Michael C

guilher...@gmail.com

unread,
Aug 16, 2013, 9:25:14 AM8/16/13
to php...@googlegroups.com
Hi,

Based on Paddy's comment on other thread, I'd like to switch my vote to +1.
As I said there, I feel odd to provide a vote based on 2 documents but only need to consider 1 of them (meta).

Nils Adermann

unread,
Aug 16, 2013, 9:48:51 AM8/16/13
to php...@googlegroups.com
+1

On 08/13/2013 03:39 PM, Phil Sturgeon wrote:
> The phpDocumentor team have for a while been working on a standard for
> PHPDoc / DocBlock tags and definitions.
>
> Pre-Draft Document
> This vote is not to make it an "Accepted" PSR, and you don't need
> to agree with all of the wording. This vote is only to move the
> PHPDoc standard from Pre-Draft to Draft.
>
> If you like the idea in general, but have feedback on wording,
> formatting, code examples, whatever, then vote yes and send a pull
> request to the phpDocumentor fork now or later.
>
> *Editor: *Mike van Riel
> *Sponsors:* Phil Sturgeon (Co-ordinator) & Donald Gilbert
>
> This vote will come to a close August 27th at 17:00 EST.
>
> As Coordinator I am still allowed to vote on behalf of my project, so:
>
> *+1 from PyroCMS*
> *
> *
> /P.S: I am currently a coordinator for two proposals at the same
> time, which is going to be a chunk of work. I'm not trying to get
> involved with every PSR ever, I am just very interested in these
> two. I wont take on any more until these are accepted./
>
> --
> You received this message because you are subscribed to the Google
> Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/php-fig/60613603-1080-4078-b103-1dc2b232fedc%40googlegroups.com?hl=en.

Paul Dragoonis

unread,
Aug 16, 2013, 9:51:35 AM8/16/13
to php...@googlegroups.com
+1


Larry Garfield

unread,
Aug 16, 2013, 5:05:37 PM8/16/13
to php...@googlegroups.com
It's a bit odd since these proposals are already pretty far along and are more developed than future proposals will probably be at this point.  The votes on the table are basically "should PHP FIG consider having a [caching|phpdoc|autoload] spec at all".

Nitpicking comes after they get through these votes. :-)

--Larry Garfield
--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

Lukas Kahwe Smith

unread,
Aug 18, 2013, 3:10:14 PM8/18/13
to php...@googlegroups.com
+1 from Jackalope
> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/60613603-1080-4078-b103-1dc2b232fedc%40googlegroups.com?hl=en.
> For more options, visit https://groups.google.com/groups/opt_out.



regards,
Lukas Kahwe Smith
sm...@pooteeweet.org



signature.asc

Larry Garfield

unread,
Aug 20, 2013, 6:58:20 PM8/20/13
to php...@googlegroups.com
+1

--Larry Garfield, Drupal

On 8/13/13 8:39 AM, Phil Sturgeon wrote:
> The phpDocumentor team have for a while been working on a standard for
> PHPDoc / DocBlock tags and definitions.
>
> Pre-Draft Document
> This vote is not to make it an "Accepted" PSR, and you don't need
> to agree with all of the wording. This vote is only to move the
> PHPDoc standard from Pre-Draft to Draft.
>
> If you like the idea in general, but have feedback on wording,
> formatting, code examples, whatever, then vote yes and send a pull
> request to the phpDocumentor fork now or later.
>
> *Editor: *Mike van Riel
> *Sponsors:* Phil Sturgeon (Co-ordinator) & Donald Gilbert
>
> This vote will come to a close August 27th at 17:00 EST.
>
> As Coordinator I am still allowed to vote on behalf of my project, so:
>
> *+1 from PyroCMS*
> *
> *
> /P.S: I am currently a coordinator for two proposals at the same
> time, which is going to be a chunk of work. I'm not trying to get
> involved with every PSR ever, I am just very interested in these
> two. I wont take on any more until these are accepted./

Nate Abele

unread,
Aug 27, 2013, 11:44:08 AM8/27/13
to php...@googlegroups.com
+1


On Tuesday, August 13, 2013 9:39:37 AM UTC-4, Phil Sturgeon wrote:
The phpDocumentor team have for a while been working on a standard for PHPDoc / DocBlock tags and definitions. 

This vote is not to make it an "Accepted" PSR, and you don't need to agree with all of the wording. This vote is only to move the PHPDoc standard from Pre-Draft to Draft. 

If you like the idea in general, but have feedback on wording, formatting, code examples, whatever, then vote yes and send a pull request to the phpDocumentor fork now or later.

Editor: Mike van Riel
Sponsors: Phil Sturgeon (Co-ordinator) & Donald Gilbert


This vote will come to a close August 27th at 17:00 EST.

As Coordinator I am still allowed to vote on behalf of my project, so:

+1 from PyroCMS

Phil Sturgeon

unread,
Aug 27, 2013, 2:15:58 PM8/27/13
to php...@googlegroups.com
Voting closed at 17:00 UTC.

For: 22
Against: 0
Abstained / No Vote: 5

The Entrance Vote has passed

According to the new workflow bylaw, this I've added this PHPDoc Standard as PSR-5, as the last PSR in the system at any status was PSR-4: Autoloading.

Check out the PSR Index to see more.

André R.

unread,
Sep 5, 2013, 3:01:04 AM9/5/13
to php...@googlegroups.com
+1 from eZ Publish


P.S. for editor/sponsors: Please find a standard way to declare array types (key and value), I only know of phplint's float[int][int], but IDE's seem to only support Type[].

Mike van Riel

unread,
Sep 5, 2013, 3:05:40 AM9/5/13
to php...@googlegroups.com
André,


On 09/05/2013 09:01 AM, André R. wrote:
+1 from eZ Publish


P.S. for editor/sponsors: Please find a standard way to declare array types (key and value), I only know of phplint's float[int][int], but IDE's seem to only support Type[].
This is captured in the new Generics notation proposal: https://github.com/phpDocumentor/fig-standards/issues/6

On Tuesday, August 13, 2013 3:39:37 PM UTC+2, Phil Sturgeon wrote:
The phpDocumentor team have for a while been working on a standard for PHPDoc / DocBlock tags and definitions. 

This vote is not to make it an "Accepted" PSR, and you don't need to agree with all of the wording. This vote is only to move the PHPDoc standard from Pre-Draft to Draft. 

If you like the idea in general, but have feedback on wording, formatting, code examples, whatever, then vote yes and send a pull request to the phpDocumentor fork now or later.

Editor: Mike van Riel
Sponsors: Phil Sturgeon (Co-ordinator) & Donald Gilbert

This vote will come to a close August 27th at 17:00 EST.

As Coordinator I am still allowed to vote on behalf of my project, so:

+1 from PyroCMS

P.S: I am currently a coordinator for two proposals at the same time, which is going to be a chunk of work. I'm not trying to get involved with every PSR ever, I am just very interested in these two. I wont take on any more until these are accepted.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

Phil Sturgeon

unread,
Sep 5, 2013, 3:28:59 PM9/5/13
to php...@googlegroups.com


On Thursday, 5 September 2013 03:01:04 UTC-4, André R. wrote:
+1 from eZ Publish

You missed the vote by a week, but thank you for letting us know you're interested. 
Reply all
Reply to author
Forward
0 new messages