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

docs: refine babel-types docs generator #13148

Merged
merged 4 commits into from Apr 14, 2021

Conversation

JLHwung
Copy link
Contributor

@JLHwung JLHwung commented Apr 13, 2021

Q                       A
License MIT

This PR revives the @babel/types docs generator. Now it supports rendering API history. Some whitespace changes are adopted to adapt to the prettier style used in babel website.

I plan to draft a new section on the alias of AST node.

Related: see babel/website#2490 for the rendered diff and preview.

@JLHwung JLHwung added the PR: Internal 🏠 A type of pull request used for our changelog categories label Apr 13, 2021
@babel-bot
Copy link
Collaborator

babel-bot commented Apr 13, 2021

Build successful! You can test your changes in the REPL here: https://babeljs.io/repl/build/45186/

@codesandbox-ci
Copy link

codesandbox-ci bot commented Apr 13, 2021

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 243518c:

Sandbox Source
babel-repl-custom-plugin Configuration
babel-plugin-multi-config Configuration

@nicolo-ribaudo nicolo-ribaudo added PR: Docs 📝 A type of pull request used for our changelog categories and removed PR: Internal 🏠 A type of pull request used for our changelog categories labels Apr 13, 2021
@nicolo-ribaudo
Copy link
Member

We might use a GH action to update babel/website when @babel/types has changes

@JLHwung
Copy link
Contributor Author

JLHwung commented Apr 13, 2021

Yeah. Since most @babel/types changes will be minor, we can add "update babel-types docs" to the todo list after new minor release.

Object.keys(t.BUILDER_KEYS)
.sort()
.forEach(function (key) {
readme.push("### " + toFunctionName(key));
Copy link
Member

@hzoo hzoo Apr 14, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is outside your PR but just wanted to note it! Looking at the rendered part again, maybe in another PR, we should have a quick section above that explains the terms "builder" and the difference between

t.anyTypeAnnotation();
t.isAnyTypeAnnotation(node, opts)
t.assertAnyTypeAnnotation(node, opts).

I would just mention that instead of manually creating the AST node as an object, we provide this interface with some assertions etc. And then the other two methods as an alias t.isX = node.type === "x", and same with assert?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure where we would do it, but it would also be nice to have a short snippet of what that code even looks like since this page assume you know what each node is. We can also link to astexplorer as a way to test it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

have a quick section above that explains the terms "builder" and the difference between

t.anyTypeAnnotation();
t.isAnyTypeAnnotation(node, opts)
t.assertAnyTypeAnnotation(node, opts).

Agreed. I have split the "API" section, tentatively, to "Node Builders" and "Aliases" in #13151, maybe we can add new sections about the usage of is* and assert*.

@JLHwung JLHwung merged commit d6d942d into babel:main Apr 14, 2021
@JLHwung JLHwung deleted the refine-babel-types-docs-generator branch April 14, 2021 20:26
@github-actions github-actions bot added the outdated A closed issue/PR that is archived due to age. Recommended to make a new issue label Jul 15, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 15, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
outdated A closed issue/PR that is archived due to age. Recommended to make a new issue PR: Docs 📝 A type of pull request used for our changelog categories
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants