search

phpDocumentor / fig-standards

Standards either proposed or approved by the Framework Interop Group
http://www.php-fig.org/
Other
360 stars 85 forks source link

Specialization: userland or PSR? #94

Closed mindplay-dk closed 6 years ago

mindplay-dk commented 9 years ago

I was just made aware of the tag specialization feature.

As per the spec and comments in #37 this could potentially be used for specializations such as :read and :write for the @property tag.

However,

projects are free to choose their own tag specializations if applicable.

And:

Tools using the PHPDoc Standard MAY interpret tag specializations that are registered with/understood by that application and apply custom behaviour

In the light of this, and the circumstances described below, I think this is a very bad idea.

Specialization, in my opinion, should either be completely reserved for userland specializations, or completely reserved for specializations defined in the PSR.

Given that:

  1. We currently have only two known/defined candidates for "specializations", e.g. @property-read and @property-write, and
  2. These are already covered by de-facto php-doc using a different syntax - a syntax change would be a substantial break from the de-facto standard, and
  3. No reservations of any specializations have been defined at this time,

I think it would be best to fully reserve this feature exclusively for userland purposes.

Fleshgrinder commented 9 years ago

The dash collides with vendor prefixes.

I am totally in favor of exclusive userland purposes, but this does not collide with @property:read and @property:write because we could handle it like well-known ports and simply state that the two are a common example for tag specialization (and of course mention the old standard).

mindplay-dk commented 9 years ago

Vendor prefixes are prefixes - it's a naming convention, it's not syntax.

I've opened an issue (#95) to discuss this issue.

mvriel commented 9 years ago

Since a Tool that uses the PHPDoc standard is a userland implementation i do not see how the quotes in the opening post conflict.

Since tags may be added beyond this specification I think the same should apply for specializations. We can add basic specialisations but userland is free to add more. It may feel slightly awkward but is consistent with how tags are handled

ashnazg commented 6 years ago

If this needs to be pursued further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig