From 9d6893d51f6698a597d518fdfb51c704d9144bee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hu=C3=A1ng=20J=C3=B9nli=C3=A0ng?= Date: Fri, 30 Apr 2021 16:08:12 -0400 Subject: [PATCH] Add alias docs for @babel/types (#13151) * add alias docs generator * fix LVal and PatternLike * sort alias covered node types * add inner links between alias and node types * review comments * tiny tweaks --- .../babel-types/scripts/generators/docs.js | 124 +++++++++++++++++- 1 file changed, 121 insertions(+), 3 deletions(-) diff --git a/packages/babel-types/scripts/generators/docs.js b/packages/babel-types/scripts/generators/docs.js index 07a44bbd3754..1b2b8e2d5d0c 100644 --- a/packages/babel-types/scripts/generators/docs.js +++ b/packages/babel-types/scripts/generators/docs.js @@ -124,17 +124,18 @@ function printAliasKeys(key, readme) { "Aliases: " + t.ALIAS_KEYS[key] .map(function (key) { - return "`" + key + "`"; + return "[`" + key + "`](#" + key.toLowerCase() + ")"; }) .join(", ") ); } } - +readme.push("### Node Builders"); +readme.push(""); Object.keys(t.BUILDER_KEYS) .sort() .forEach(function (key) { - readme.push("### " + toFunctionName(key)); + readme.push("#### " + toFunctionName(key)); readme.push(""); readme.push("```javascript"); readme.push( @@ -159,4 +160,121 @@ Object.keys(t.BUILDER_KEYS) readme.push(""); }); +function generateMapAliasToNodeTypes() { + const result = new Map(); + for (const nodeType of Object.keys(t.ALIAS_KEYS)) { + const aliases = t.ALIAS_KEYS[nodeType]; + if (!aliases) continue; + for (const alias of aliases) { + if (!result.has(alias)) { + result.set(alias, []); + } + const nodeTypes = result.get(alias); + nodeTypes.push(nodeType); + } + } + return result; +} +const aliasDescriptions = { + Binary: + "A cover of BinaryExpression and LogicalExpression, which share the same AST shape.", + Block: "Deprecated. Will be removed in Babel 8.", + BlockParent: + "A cover of AST nodes that start an execution context with new [LexicalEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `let` and `const` declarations.", + Class: + "A cover of ClassExpression and ClassDeclaration, which share the same AST shape.", + CompletionStatement: + "A statement that indicates the [completion records](https://tc39.es/ecma262/#sec-completion-record-specification-type). In other words, they define the control flow of the program, such as when should a loop break or an action throws critical errors.", + Conditional: + "A cover of ConditionalExpression and IfStatement, which share the same AST shape.", + Declaration: + "A cover of any [Declaration](https://tc39.es/ecma262/#prod-Declaration)s.", + EnumBody: "A cover of Flow enum bodies.", + EnumMember: "A cover of Flow enum membors.", + ExportDeclaration: + "A cover of any [ExportDeclaration](https://tc39.es/ecma262/#prod-ExportDeclaration)s.", + Expression: + "A cover of any [Expression](https://tc39.es/ecma262/#sec-ecmascript-language-expressions)s.", + ExpressionWrapper: + "A wrapper of expression that does not have runtime semantics.", + Flow: "A cover of AST nodes defined for Flow.", + FlowBaseAnnotation: "A cover of primary Flow type annotations.", + FlowDeclaration: "A cover of Flow declarations.", + FlowPredicate: "A cover of Flow predicates.", + FlowType: "A cover of Flow type annotations.", + For: + "A cover of [ForStatement](https://tc39.es/ecma262/#sec-for-statement)s and [ForXStatement](#forxstatement)s.", + ForXStatement: + "A cover of [ForInStatements and ForOfStatements](https://tc39.es/ecma262/#sec-for-in-and-for-of-statements).", + Function: + "A cover of functions and [method](#method)s, the must have `body` and `params`. Note: `Function` is different to `FunctionParent`.", + FunctionParent: + "A cover of AST nodes that start an execution context with new [VariableEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `var` declarations. FunctionParent did not include `Program` since Babel 7.", + Immutable: + "A cover of immutable objects and JSX elements. An object is [immutable](https://tc39.es/ecma262/#immutable-prototype-exotic-object) if no other properties can be defined once created.", + JSX: + "A cover of AST nodes defined for [JSX](https://facebook.github.io/jsx/).", + LVal: + "A cover of left hand side expressions used in the `left` of assignment expressions and [ForXStatement](#forxstatement)s. ", + Literal: + "A cover of [Literal](https://tc39.es/ecma262/#sec-primary-expression-literals)s, [Regular Expression Literal](https://tc39.es/ecma262/#sec-primary-expression-regular-expression-literals)s and [Template Literal](https://tc39.es/ecma262/#sec-template-literals)s.", + Loop: "A cover of loop statements.", + Method: "A cover of object methods and class methods.", + ModuleDeclaration: + "A cover of ImportDeclaration and [ExportDeclaration](#exportdeclaration)", + ModuleSpecifier: + "A cover of import and export specifiers. Note: It is _not_ the [ModuleSpecifier](https://tc39.es/ecma262/#prod-ModuleSpecifier) defined in the spec.", + ObjectMember: + "A cover of [members](https://tc39.es/ecma262/#prod-PropertyDefinitionList) in an object literal.", + Pattern: + "A cover of [BindingPattern](https://tc39.es/ecma262/#prod-BindingPattern) except Identifiers.", + PatternLike: + "A cover of [BindingPattern](https://tc39.es/ecma262/#prod-BindingPattern)s. ", + Private: "A cover of private class elements and private identifiers.", + Property: "A cover of object properties and class properties.", + Pureish: + "A cover of AST nodes which do not have side-effects. In other words, there is no observable behaviour changes if they are evaluated more than once.", + Scopable: + "A cover of [FunctionParent](#functionparent) and [BlockParent](#blockparent).", + Statement: + "A cover of any [Statement](https://tc39.es/ecma262/#prod-Statement)s.", + TSBaseType: "A cover of primary TypeScript type annotations.", + TSEntityName: "A cover of ts entities.", + TSType: "A cover of TypeScript type annotations.", + TSTypeElement: "A cover of TypeScript type declarations.", + Terminatorless: + "A cover of AST nodes whose semantic will change when a line terminator is inserted between the operator and the operand.", + UnaryLike: "A cover of UnaryExpression and SpreadElement.", + UserWhitespacable: "Deprecated. Will be removed in Babel 8.", + While: + "A cover of DoWhileStatement and WhileStatement, which share the same AST shape.", +}; +const mapAliasToNodeTypes = generateMapAliasToNodeTypes(); +readme.push("### Aliases"); +readme.push(""); +for (const alias of [...mapAliasToNodeTypes.keys()].sort()) { + const nodeTypes = mapAliasToNodeTypes.get(alias); + nodeTypes.sort(); + if (!(alias in aliasDescriptions)) { + throw new Error( + 'Missing alias descriptions of "' + + alias + + ", which covers " + + nodeTypes.join(",") + ); + } + readme.push("#### " + alias); + readme.push(""); + readme.push(aliasDescriptions[alias]); + readme.push("```javascript"); + readme.push("t.is" + alias + "(node);"); + readme.push("```"); + readme.push(""); + readme.push("Covered nodes: "); + for (const nodeType of nodeTypes) { + readme.push("- [`" + nodeType + "`](#" + nodeType.toLowerCase() + ")"); + } + readme.push(""); +} + process.stdout.write(readme.join("\n"));