search

phpDocumentor / fig-standards

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

Standard indicator tag #137

Closed mindplay-dk closed 5 years ago

mindplay-dk commented 7 years ago

We have on numerous occasions run into things we can't improve or fix, because changing things would conflict with de-facto standard php-doc.

As a result, a lot of discussions either end with a sigh in resignation to the fact that we're not allowed to change various important aspects of syntax and features, or they dead-end with a stalemate an no ability to make any final decisions, blocking us from (for example) meeting new practical requirements for PHP 7, etc. - you get the idea...

What if we introduced a file-level tag that indicates which standards apply to the file?

For example:

<?php

/**
 * @psr 5
 */

At the file-level, this would indicate following new standards and syntax. Simple.

Existing tools that do not wish to support psr-5 can then simply detect this tag and ignore the whole file.

New tools can know that the file follows the specified standard.

We could even allow multiple future standards, like, let's say we standardize on an inline markdown syntax at some point, and let's say that's psr-99:

<?php

/**
 * @psr 5, 99
 */

Or perhaps we even assign names to them, for human-friendliness, e.g.:

<?php

/**
 * @psr doc md
 */

Thoughts?

Fleshgrinder commented 7 years ago

I do not think that this is necessary for various reasons I will explain shortly. First off, I think this approach to PSR-5 is dead anyways and that we should consider forming a new working group and start a new attempt.

As the two of us already agreed once, PSR-5 should only be for PHP 5 and keep up backwards compatibility with the existing quasi phpDocumentor standard. However, another PSR-7 should be made for PHP 7 and take future compatibility more into account while being developed.

This directly voids the requirement for such a tag because software that is targeting PHP 5 implements PSR-5 while software targeting PHP 7 implements PSR-X. Of course one could provide software that supports both but the user would need to decide which of both PSR standards to use.

mindplay-dk commented 5 years ago

Closing to avoid increasing the scope and distracting from pending work on the PSRs.