[VOTE][Entrance]: PHPDoc Standard

[Phil Sturgeon]

The phpDocumentor team have for a while been working on a standard for PHPDoc / DocBlock tags and definitions. 

Pre-Draft Document

Meta 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.

[Drak]

+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]

+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]

+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.

Avoiding a Goat Rodeo

[Pádraic Brady]

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]

I am not really sure whether an editor may vote, if not please ignore this.

If so: +1 from phpDocumentor

[Evert Pot]

+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]

+1 from Joomla

[Pádraic Brady]

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.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/28add8eb-e837-460a-a5aa-604a05a25d9f%40googlegroups.com?hl=en.

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

--

[Jordi Boggiano]

+1

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

[Brett Bieber]

+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.

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.

--
Brett Bieber

[Paul M. Jones]

+1 from Solar/Aura/etc


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

[Fabien Potencier]

+1

[Dowling, Michael]

+1 from AWS

[William Durand]

+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.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/25975d5f-8d54-4de4-b2fd-aabbad31e58d%40googlegroups.com.

[Taylor Otwell]

+1 From Laravel

[guilher...@gmail.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.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/ed12a1df-74f0-4265-9858-77c0f897f2ee%40googlegroups.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]

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>

This is under discussion in issue https://github.com/phpDocumentor/fig-standards/issues/6

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

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAFp73XvKBdUdXZ8muudZuaS3QaiR_P5pzRZMGS80S2-AAOGWMQ%40mail.gmail.com.

[Karsten Dambekalns]

Hi.

Phil Sturgeon wrote:
> 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.

+1 from TYPO3 Flow.

Regards,
Karsten

[Michael C]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/520DDB59.9050000%40gmail.com.

[guilher...@gmail.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]

+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

> <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.

[Paul Dragoonis]

+1

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/520E2DC3.9010006%40naderman.de.

[Larry Garfield]

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.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAFp73XvNOOB9h5-hgUCK70Gke_U%3DH_A_46m77iQrke2B3D7MVA%40mail.gmail.com.

[Lukas Kahwe Smith]

+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

[Larry Garfield]

+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

> <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./

[Nate Abele]

+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. 

Pre-Draft Document

Meta 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

[Phil Sturgeon]

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.]

+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]

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. 

Pre-Draft Document

Meta 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/2d7ecab6-b809-480b-8f91-993f24fc5193%40googlegroups.com.

[Phil Sturgeon]

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.