Looks like PSR-5 is being revived, and I understand that the working group is just forming.
I'd like to bring up an issue with the current definitions of the @api and @internal tags. Per the current definition, the @api tag marks members as being part of the public API, and @internal is described as being it's "counterpart", which I believe is incorrect. These tags effectively define public vs internal visibility of members, but, according to their current definition, they are not complementary at all - rather, they are mutually exclusive. In effect, adding even a single @api annotation to a codebase would mean that a tool needs to turn the visibility rules upside-down and ignore any @internal tags entirely. Alternatively, the tools would need a switch to toggle whether the default assumption, which is even more confusing, since these annotations will work differently from project to project. In other words, the preseence of an @api tag i a codebase has side-effects that spread to the entire rest of the codebase, effectively rendering the `@internal` annotation useless. In my opinion, a single annotation should not be allowed to nullify another annotation-type entirely - you effectively end up with two "modes" for these annotations, and you burden tools with the effort of having to analyze the entire codebase (!) before they can determine the visibility of any of it's members. (While most offline tools will *probably* be able to handle this, determining effective visibility in run-time doc-block reflection facilities is practically not feasible.) Explicitly marking specific members of your codebase as internal makes it easier to progressively flag portions of your API as internal, and it's more in tune with how PHP and doc-blocks work in general: narrowing types for static analysis, adding tighter constraints than is possible with PHP, and so on. In the same vein, the @internal annotation should narrow the scope of the public API. I believe it's also closer to the current interpretation in PHP Storm. So I'd like to propose changing the definitions of these tags: The @api tag would be for documentation purposes only - e.g. could be used to highlight the primary portion of the public API in a special section of generated documentation. The @internal tag would work much the same as it does now, but shouldn't be described as having any relationship with the @api tag. Thoughts? -- 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 [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/2af70cf0-6288-4c02-a77e-87e55d7de7d4%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
