Add support for @ignore in the docgen tool #42198
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…found. This aligns better with how core handles documentation around internal functions.
ryanwelcher
added
[Type] Enhancement
|
Size Change: 0 B Total Size: 1.25 MB ℹ️ View Unchanged
|
dmsnell
approved these changes
Jul 6, 2022
There was a problem hiding this comment.
Please lean on other review; I don't have strong feelings about this. Not sure we should assume that a standard approach in PHP implies it should translate into JS so I don't think I agree with the premise, but I feel like docgen is something not worth spending too much time debating about.
Supporting it in docgen is one thing, but we should maybe raise the conversation in the Make chat when discussing a project-wide convention. People may have opinions there.
You will find occurrences of
It would be great though to confirm with core committers that it is the correct usage for the Gutenberg project. |
gziolo
approved these changes
Jul 7, 2022
Totally agree. This PR is not intended to make a statement about how things should be documented but rather to ensure that whatever tag is used ( To that end, I think we need to add |
|
It looks like |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
The current
docgentool does not recognize the@ignoretag. This PR adds that functionality into the tool to allow items to be marked as@ignoreso that they won't be added to the documentation.This is part of a larger effort to improve the Data Modules reference - #42125
Why?
Currently, only items tagged as
@privateare not documented and if the tool also supports@ignoreit will allow us to match how core indicates that an item should not be documented.Testing Instructions
package/docgendirectorytest.jsin the root with the following code:node ./bin/cli.js test.jsand check the generated file to confirm the function is documented@ignorenode ./bin/cli.js test.jsand check the generated file to confirm the function is NOT documented