BigPipe provides functionality, not an API: mark all classes & interfaces @internal

Thanks for this issue. https://www.drupal.org/core/d8-bc-policy already says that service and controller implementations are not part of the public API. So I think we only need @internal added to BigPipeInterface and BigPipeResponse. I think we should also add a sentence to each of those two explaining why they're internal.

How about this instead? This changes some wording, and also moves the @internal from BigPipeInterface to just the sendContent() method. That way, contrib modules such as big_pipe_sessionless, or whatever else is experimenting with extending big_pipe, can safely type hint to BigPipeInterface without IDE warnings. Meanwhile, https://www.drupal.org/core/d8-bc-policy#interfaces gives room for us to add new methods to the interface.

wouldn't it be safer to mark all of these @internal?

I don't think so. I don't see why big_pipe services and controllers should be considered any more internal than any other module's services and controllers. If at some point we want to change our bc policy across the board for services and controllers, then at that point we'll need to add @internal to those classes in many modules, and can cover big_pipe ones as part of that.

Committed pushed to 8.3.x and cherry-picked to 8.2.x, thanks!

I wonder, why do we provide an interface at all if we don't mean it as an extension point? Should we remove it? We can do so even though the API was not @internal before since BigPipe was only ever in alpha.

BTW, I do think everything that's internal should be explicitly marked so, rather than relying on the handbook page. See #2550249: [meta] Document @internal APIs both explicitly in phpdoc and implicitly in d.o documentation. So IMO Wim's first patch was fine, although we can scope

Remove BigPipeInterface and move all of its docs to the implementation.

+1.

Add @internal to all other classes like in #2?

Per @catch's suggestion, let's instead do this in bulk patches across core for each of the "kinds of thing" the other classes are in #2550249: [meta] Document @internal APIs both explicitly in phpdoc and implicitly in d.o documentation. That way each kind of internal-by-default thing will be consistent.

Hm, I'm not sure how that would guarantee that this would ever happen.

#2550249: [meta] Document @internal APIs both explicitly in phpdoc and implicitly in d.o documentation will not be marked fixed without the child issues being done for each of the kinds of internal things . (And it's a pet concern for committers since API visibility and stability is the hardest problem we have to hash out on a daily basis.) :) We could also kick things off by filing child issues of the meta for (e.g.) "Mark controllers as @internal", "Mark foo services as internal", etc. for the things we would have fixed here.