PSR-5: conflicting @api and @internal tags

[Rasmus Schultz]

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?

[Adrien Crivelli]

I agree with you that having both only lead to confusion. However we could certainly argue a long time about which one should be kept.

When starting a project from scratch it's probably easier to mark a few method as public, rather than most code as private. It seems more "secure" to whitelist public thing, rather than blacklist private thing. On the other hand, like you said, for an existing project, it's likely easier to gradually make things private. Maybe that's the reason both annotations exist ? to allow to choose between "whitelist" or "blacklist" workflow ?

But whatever reason may have lead to the current situation, I would be in favor to keep only one, whichever it is.

It might even be possible to write a tool to migrate from one annotation to another, once the choice is settled.

[Rasmus Schultz]

> It seems more "secure" to whitelist public thing, rather than blacklist private thing

The problem is that you're arguing with the language, where everything is public - and not just by default.

To start from the assumption that everything is internal is simply "wrong" in the context of PHP - it simply isn't, it's public by default.

That's not to say you couldn't deviate from that in doc-blocks, but it would be inconsistent with the language - and, as said, inconsistent with the way doc-blocks work in general, where you're generally starting with PHP's own constraints being the default, and permitting you to narrow those to set tighter constraints than is possible with PHP.

When you're suggesting the opposite, you're really suggesting doc-blocks should make the opposite assumption to what's true in the language.

That would be confusing - and especially so, if this behavior is conditional on whether any @api doc-blocks are present in the codebase; you add the first @api doc-block and, boom, all your @internal doc-blocks are now garbage. Doesn't make sense. Nobody likes side-effects.

If this were a discussion about the default in the language, I'd be all for private/internal being the default - but the language is set in stone, and in my opinon, the php-doc standard should build and expand upon the annotations that are possible in the language itself. It shouldn't replace them.

[Adrien Crivelli]

I think the argument for coherence with the language is a strong one. And it would be fine with me to implement your original suggestion.

[Chuck Burgess]

Historically speaking, @internal was the only tag available of the two, and was designed for making it possible for two levels of documentation:

* public level code for consumers to read

* private level code for developers-of-this-code to read

This assumed that the default use of phpDocumentor was for producing the former, whereas adding the --parseprivate option would allow for creation of the latter.

What this scheme did not address is "package scope", where publicly scoped elements are only public so that other classes in the package can use them, but the intention is *not* for consumers of the package to use them.  Thus was born, in the wild, the custom @api tag.  This was not recognized as anything specific/special in phpDocumentor until v2.  Further, in v2, the tag still doesn't hide any public elements that are not marked with @api.  The only behavior specified for this tag is that any output templates *that choose to* should list all @api elements in a special sidebar display.

Honestly, I'm ok to *drop* the @api tag from the tag catalog, and let it live as a custom tag in the wild.  It's really only in the PSR draft because the draft was sourced from phpDocumentor v2's manual.  I've never personally used it to manage public vs package scope in my docs... I've instead used tighter runtime configurations for phpDocumentor to parse and show only the API-level elements that I want in my consumer's documentation.

CRB

[Stefano Torresi]

I agree with dropping @api entirely, as it looks like it was introduced for a very specific requirement of a phpDocumentor presentation use case.

[Robbie Averill]

Hi all,

I think @internal is much more useful than @api. Usually I would assume that my making a method public would declare it as part of my API, but having @internal to explicitly opt out of that is useful.

Cheers,

Robbie

On Thu, 27 Sep 2018 at 14:45, Stefano Torresi <ste...@torresi.io> wrote:

I agree with dropping @api entirely, as it looks like it was introduced for a very specific requirement of a phpDocumentor presentation use case.

--
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/CAFojS1vT10dHOo7WEy%3D82TYdrEkPFDie358nxUs4y1OOMS15%2Bw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

Robbie Averill | Senior Developer

04 978 7330

http://silverstripe.com/

[Chuck Burgess]

On Tuesday, September 18, 2018 at 3:21:19 AM UTC-5, Rasmus Schultz wrote:

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?

Hey Rasmus,

If we do go with keeping both tags in the PSR-19 catalog, I think we should at least change the descriptions as you've suggested here.  Do you want to make a PR for that?  We can always consider a drop of the @api tag as a separate discussion. 

CRB

[Rasmus Schultz]

Hi Chuck,

I can do a PR, but where's the repository?

- Rasmus

> --
> You received this message because you are subscribed to a topic in the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/php-fig/tix3-i6YCQQ/unsubscribe.
> To unsubscribe from this group and all its topics, 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/5ee5e5b0-7c38-42cf-a4ee-8e517572031b%40googlegroups.com.

[Chuck Burgess]

https://github.com/php-fig/fig-standards/pulls

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/CADqTB_iwFq%3D-FyCiTn4dFL2pKO-D6Y3F5kREpgzJkNXDuJ_ggg%40mail.gmail.com.

[Chuck Burgess]

I now have the old sandbox repo updated, so we can resume using it instead of using the FIG repo itself:

https://github.com/phpDocumentor/fig-standards/pulls

CRB

On Sunday, September 30, 2018 at 2:13:32 PM UTC-5, Chuck Burgess wrote:

https://github.com/php-fig/fig-standards/pulls

On Sun, Sep 30, 2018, 14:10 Rasmus Schultz <ras...@mindplay.dk> wrote:

Hi Chuck,

I can do a PR, but where's the repository?

- Rasmus

On Fri, Sep 28, 2018 at 9:06 PM Chuck Burgess <demon...@gmail.com> wrote:
>
> On Tuesday, September 18, 2018 at 3:21:19 AM UTC-5, Rasmus Schultz wrote:
>>
>> 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?
>>
>
>
> Hey Rasmus,
> If we do go with keeping both tags in the PSR-19 catalog, I think we should at least change the descriptions as you've suggested here.  Do you want to make a PR for that?  We can always consider a drop of the @api tag as a separate discussion.
> CRB
>
> --
> You received this message because you are subscribed to a topic in the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/php-fig/tix3-i6YCQQ/unsubscribe.

> To unsubscribe from this group and all its topics, send an email to php-fig+unsubscribe@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/5ee5e5b0-7c38-42cf-a4ee-8e517572031b%40googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

--
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+unsubscribe@googlegroups.com.