Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build Tooling: Update use of docgen to target only unstable APIs named by convention #15197

Closed
aduth opened this issue Apr 25, 2019 · 5 comments · Fixed by #63673
Closed

Build Tooling: Update use of docgen to target only unstable APIs named by convention #15197

aduth opened this issue Apr 25, 2019 · 5 comments · Fixed by #63673
Assignees
Labels
Good First Issue An issue that's suitable for someone looking to contribute for the first time Needs Dev Ready for, and needs developer efforts [Status] In Progress Tracking issues with work in progress [Tool] Docgen /packages/docgen [Type] Build Tooling Issues or PRs related to build tooling [Type] Task Issues or PRs that have been broken down into an individual action to take

Comments

@aduth
Copy link
Member

aduth commented Apr 25, 2019

Previously: #14557 (comment), #14565

The coding guidelines surrounding Unstable and Experimental APIs are very specific in how they ought to be named.

An experimental or unstable function or object should be prefixed respectively using __experimental or __unstable.

https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#experimental-and-unstable-apis

The current docgen script is lenient toward variations of these guidelines, due to preexisting issues described at #14557 (comment) .

Task: The script should be made non-lenient.

Reason: By removing leniency, it should help make clear where coding guidelines are being violated, since the invalid token would be included (wrongly) in the generated documentation.

Blocked by: Prexisting issues should be resolved (aligned to the guideline).

@aduth aduth added [Type] Task Issues or PRs that have been broken down into an individual action to take [Type] Build Tooling Issues or PRs related to build tooling [Status] Blocked Used to indicate that a current effort isn't able to move forward [Tool] Docgen /packages/docgen labels Apr 25, 2019
@aduth
Copy link
Member Author

aduth commented Apr 25, 2019

Blocked by: Prexisting issues should be resolved (aligned to the guideline).

Upon further investigation, I find there are two existing issues:

@gziolo gziolo added Needs Dev Ready for, and needs developer efforts Good First Issue An issue that's suitable for someone looking to contribute for the first time and removed [Status] Blocked Used to indicate that a current effort isn't able to move forward labels Oct 20, 2019
@gziolo
Copy link
Member

gziolo commented Oct 20, 2019

This is what is still left to do for unstable__bootstrapServerSideBlockDefinitions:

For the above reasons, I suggest that once #15173 is merged, we simply add a @Private tag to the exported symbol's DocBlock as an alternative approach to exclude it from the documentation

@ryanwelcher
Copy link
Contributor

With #42198, we can also use @ignore.

@ryanwelcher
Copy link
Contributor

@gziolo is this issue still relevant?

@gziolo
Copy link
Member

gziolo commented Aug 3, 2022

With #42198, we can also use @ignore.

Yes, we should mark unstable__bootstrapServerSideBlockDefinitions with @ignore or something similar and consider this issue complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Good First Issue An issue that's suitable for someone looking to contribute for the first time Needs Dev Ready for, and needs developer efforts [Status] In Progress Tracking issues with work in progress [Tool] Docgen /packages/docgen [Type] Build Tooling Issues or PRs related to build tooling [Type] Task Issues or PRs that have been broken down into an individual action to take
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants