docgen: Omit docblocks with private tag #15173
Conversation
aduth
added
[Type] Developer Documentation
aduth
requested review from
ellatrix,
gziolo,
mkaz,
noisysocks,
oandregal and
youknowriad
as code owners
| @@ -1,3 +1,16 @@ | |||
| let _lastSum; | |||
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
I don't think this particular fixture is used anywhere. For Markdown we should add the test here.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I don't think this particular fixture is used anywhere.
Should it be removed here then?
There was a problem hiding this comment.
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.
| @@ -1,4 +1,7 @@ | |||
| const getTagsByName = ( tags, ...names ) => tags.filter( ( tag ) => names.some( ( name ) => name === tag.title ) ); | |||
aduth
force-pushed
the
add/docgen-omit-private
branch
from
5cdb16b
to
01d3776
Compare
|
Rebased to:
|
|
@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. |
Closes #14294
This pull request seeks to enhance
@wordpress/docgento omit symbols which include a@privatetag in their JSDoc. In turn, this was used to omit the reference towp.blocks.childrenfrom 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
docgento 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: