Settings Tray provides functionality, not an API: mark PHP and JS as internal

Here is a patch.

The only thing that's an API, is the declaration of "off_canvas forms".

and

Add a outside_in.api.php file to document the actual API.

The way we are marking form as off_cavnvas is in outside_in_block_alter but this is because these are existing blocks.
For a module that define it's own blocks it would be more correct to update add an 'off_canvas' form handler in their blocks plugin file.

How would that be documented in an .api.php file?

+++ b/core/modules/outside_in/js/off-canvas.es6.js
@@ -5,6 +5,8 @@
+ * @internal

JSDoc does not use @internal. I'd suggest using @private or @protected depending on the actual goal of this documentation.

- Switch JSDoc to use @private, http://usejsdoc.org/tags-private.html

Not RTBC-blocking, but we should definitely have a framework manager review this one.

+++ b/core/modules/outside_in/css/outside_in.tabledrag.css
@@ -3,6 +3,9 @@
  * @see tabledrag.js
+ *
+ *
+ * @internal

+++ b/core/modules/outside_in/css/outside_in.theme.css
@@ -1,6 +1,9 @@
  * Visual styling for Settings Tray module.
+ *
+ *
+ * @internal

Are there supposed to be double blank lines here?

+++ b/core/modules/outside_in/src/OutsideInManager.php
@@ -8,6 +8,8 @@
 class OutsideInManager implements OutsideInManagerInterface {

+++ b/core/modules/outside_in/src/OutsideInManagerInterface.php
@@ -4,6 +4,8 @@
 interface OutsideInManagerInterface {

If it's purely internal code, then why is there an interface for it?

@xjm is apparently a broken record. See #2835604-14: BigPipe provides functionality, not an API: mark all classes & interfaces @internal and @Wim Leers' reply in #15 following.

#2835758: Remove BigPipeInterface and move all of its docs to the implementation is the issue where BigPipe was actually de-interfaced.

Can we remove that interface, or spin off a separate issue to do so? Marking an interface @internal just seems like conflicting information, or "letter but not the spirit", outside of some weird/edgecase scenarios. Ideally we'd do both this and that before marking Settings Tray beta and I guess it wouldn't need to block this (we did it as a followup for BigPipe) but it does cause mental discordance for me in this patch. :P

Let's get that followup filed and remove the blank lines whitespace changes at least. :)

Edit: I fail at reading. @Wim Leers clarified that the interface has already been removed and I confirmed this in the codebase. :)

Edit 2: But let's still remove the whitespace changes. It's fine to leave it at RTBC for such a trivial cleanup, but leaving things for committers to do on commit can be error-prone and adds more work to the commit process. :)

Also a note that I'm not totally confident about the way we're marking the templates internal. That pattern doesn't exist anywhere in core. Bartik and Seven are considered internal, but that's indicated in their .info files rather than their templates. Similarly, I didn't find any examples of CSS files being marked internal in this way. I pinged @lauriii and @Cottser about it.

Discussed this with @Cottser. I also realized that module templates and CSS are considered internal anyway, by default, and we don't have a best practice for marking that yet anywhere. So let's remove the CSS and template hunks from this patch, and just keep the PHP and JS hunks.

I posted about both that question and the JS @private use here: #2550249: [meta] Document @internal APIs both explicitly in phpdoc and implicitly in d.o documentation

@xjm ok here is just the PHP and JS files.

re #17 and #18.2 all extra lines where in CSS files so not problem anymore

Forgot to save retitling the issue before commit.

Committed to 8.4.x, thanks!

An 8.3.x backport would look different because of the JS file locations. It could be backported since it's just documenting the correct state of this functionality, but leaving against 8.4.x now.

Changing to new settings_tray.module component. @drpal thanks for script help! :)