API docs are publishing internal documentation as public

[runspired]

code-doc comments marked @internal are now displaying as public API documentation on the ember website api docs.

historically ember-data used this to enable us to document things for contributor tooling that should not be documented in the api docs

you can see an example of this here, underscored methods now show up as public. In the source code they are marked only as @internal not as @public

[jenweber]

My expectation is that docs without @public should not show up, regardless of their other labels. This is pretty strange.

To solve this will probably require a fix at the level of ember-jsonapi-docs, but I'm not sure.

[amyrlam]

Some notes from @acorncom about the implementation (copying here, cause seems like could be useful for the mtg, from: https://discord.com/channels/480462759797063690/480777444203429888/839746419521748992)

DB:

• from what I’m seeing browsing the api docs generation code, it’s focused on consuming prebuilt yuidocs files that are published as part of the ember or ember data npm packages: https://github.com/ember-learn/ember-jsonapi-docs/blob/9bd4e3765cd3fedacf52797fac5cb5535b2a878e/lib/fetch-yui-docs.js#L38
• And that approach started here: [BUGFIX] Includes yuidoc's output data.json to published package emberjs/data#6252
• With some further tests you built to ensure the yuidocs output had the appropriate output here: [TESTS] improve docs coverage emberjs/data#6735
• So I think that’s probably something that needs adjustment within the ember data repo from what I can tell, am I reading that wrong?

CT:

• docs are appearing there that don’t get caught by our tests
• I suspect the tests filter out for only things marked public or private but I could check on that

[jenweber]

@runspired would it work to add @private to all the @internal docs? That's the easiest way to ensure that docs don't show up as public moving forward.

Another option is to move the "internal" functions into their files, and configure YUIdoc in the data repo to ignore certain file paths.

Is @internal for intellisense purposes when developing, or something else?

[runspired]

@jenweber it's for intellisense when developing. I've noticed since opening this issue that not all things marked internal show up, only some. I think there may more to this mystery, I'll keep investigating but for now I've got a PR to put up that will convert all internal docs to either private or no-tag.

[runspired]

@jenweber after further investigation, any doc comment not marked @private is considered public, not just those using @internal. What's more, it turns out that many public docs have been depending on that since we'd never marked them explicitly public. I wonder if this just never worked the way we thought it did.

Edit: seems we knew this at one time

// docs without internal and without a private flag are published as public by default

(a note from our own docs tests)