docgen: Omit docblocks with private tag

[aduth]

Closes #14294

This pull request seeks to enhance @wordpress/docgen to omit symbols which include a @private tag in their JSDoc. In turn, this was used to omit the reference to wp.blocks.children from the Blocks API documentation.

Open Questions:

There might be a question as to how or if we choose to omit deprecated APIs from the documented output, as in this case the API is technically deprecated. If we choose to omit this deprecated API, should we do the same for all (or should it be an option of docgen to omit deprecated APIs?). Otherwise, should this API not be marked as private and instead simply marked as deprecated, but allowed to be included in the documented output?

Testing Instructions:

Verify there are no changes from running npm run docs:build.

Ensure unit tests pass:

npm run test-unit

[aduth]

For what it's worth, these test fixtures aren't super valuable in their current form, since this could be totally wrong, and the tests still wouldn't fail, because the output isn't regenerated as part of the test, but presumably as a separate manual process.

Related: #13329 (comment)

[oandregal]

I don't think this particular fixture is used anywhere. For Markdown we should add the test here.

[aduth]

I don't think this particular fixture is used anywhere. For Markdown we should add the test here.

But it's not the formatter which is responsible to exclude the private DocBlocks, it occurs in the engine.js filtering.

[aduth]

I don't think this particular fixture is used anywhere.

Should it be removed here then?

[oandregal]

Should it be removed here then?

Yes.

But it's not the formatter which is responsible to exclude the private DocBlocks, it occurs in the engine.js filtering.

Oh, I see now, commented too quickly. The ignored symbols are actually filtered out by the CLI, not the formatter or the engine, so it's more tricky to test.

Filtering symbols (by name or tag) shouldn't be something the CLI takes care of. Ideally, we would push this code down to get-intermediate-representation.js. For the purpose of shipping this, I'm fine if we defer that refactor until later provided that we create an issue to track it.

[oandregal]

great little extraction

[aduth]

Rebased to:

• Resolve conflict
• Squash a few commits
• Remove the markdown fixtures files

[aduth]

@nosolosw At your convenience: Do you have any other thoughts here? As I see it, it seems in good shape after changes stemming from your last round of feedback.

[oandregal]

Let's get this in, it's a great addition I personally wanted for some time. I'm merging into master myself as I'm working on something that will benefit from having this already present :)