diff --git a/src/babel/traversal/path/ancestry.js b/src/babel/traversal/path/ancestry.js index 25942eb36b..cdfdfde44e 100644 --- a/src/babel/traversal/path/ancestry.js +++ b/src/babel/traversal/path/ancestry.js @@ -2,7 +2,8 @@ import * as t from "../../types"; import NodePath from "./index"; /** - * Description + * Call the provided `callback` with the `NodePath`s of all the parents. + * When the `callback` returns a truthy value, we return that node path. */ export function findParent(callback) { @@ -15,7 +16,7 @@ export function findParent(callback) { } /** - * Description + * Walk up the tree until we hit a parent node path in a list. */ export function getStatementParent() { @@ -139,7 +140,9 @@ export function getDeepestCommonAncestorFrom(paths: Array, filter?: Fu } /** - * Description + * Build an array of node paths containing the entire ancestry of the current node path. + * + * NOTE: The current node path is included in this. */ export function getAncestry() { @@ -168,7 +171,7 @@ export function inType() { } /** - * Description + * Check if we're inside a shadowed function. */ export function inShadow() { diff --git a/src/babel/traversal/path/introspection.js b/src/babel/traversal/path/introspection.js index 4495520e06..b1139444fb 100644 --- a/src/babel/traversal/path/introspection.js +++ b/src/babel/traversal/path/introspection.js @@ -148,7 +148,7 @@ export function isCompletionRecord(allowInsideFunction?) { } /** - * Description + * Check if the current node is a directive. */ export function isDirective() { @@ -226,7 +226,7 @@ export function referencesImport(moduleSource, importName) { } /** - * Description + * Get the source code associated with this node. */ export function getSource() { diff --git a/src/babel/traversal/path/modification.js b/src/babel/traversal/path/modification.js index 0275d7a2bb..44c09ed373 100644 --- a/src/babel/traversal/path/modification.js +++ b/src/babel/traversal/path/modification.js @@ -3,7 +3,7 @@ import NodePath from "./index"; import * as t from "../../types"; /** - * Description + * Insert the provided nodes before the current one. */ export function insertBefore(nodes) { @@ -75,7 +75,8 @@ export function _maybePopFromStatements(nodes) { } /** - * Description + * Insert the provided nodes after the current one. When inserting nodes after an + * expression, ensure that the completion record is correct by pushing the current node. */ export function insertAfter(nodes) { @@ -108,7 +109,7 @@ export function insertAfter(nodes) { } /** - * Description + * Update all sibling node paths after `fromIndex` by `incrementBy`. */ export function updateSiblingKeys(fromIndex, incrementBy) { @@ -121,10 +122,6 @@ export function updateSiblingKeys(fromIndex, incrementBy) { } } -/** - * Description - */ - /** * Description */ @@ -200,7 +197,8 @@ export function pushContainer(listKey, nodes) { } /** - * Description + * Hoist the current node to the highest scope possible and return a UID + * referencing it. */ export function hoist(scope = this.scope) { diff --git a/src/babel/traversal/path/removal.js b/src/babel/traversal/path/removal.js index fc6175ef2a..c7b45a4582 100644 --- a/src/babel/traversal/path/removal.js +++ b/src/babel/traversal/path/removal.js @@ -11,7 +11,8 @@ export function remove() { } /** - * Description + * Dangerously remove the current node. This may sometimes result in a tainted + * invalid AST so use with caution. */ export function dangerouslyRemove() { diff --git a/src/babel/traversal/path/replacement.js b/src/babel/traversal/path/replacement.js index 26cc1f9307..94456872dd 100644 --- a/src/babel/traversal/path/replacement.js +++ b/src/babel/traversal/path/replacement.js @@ -32,7 +32,11 @@ var hoistVariablesVisitor = { }; /** - * Description + * Replace a node with an array of multiple. This method performs the following steps: + * + * - Inherit the comments of first provided node with that of the current node. + * - Insert the provided nodes after the current node. + * - Remove the current node. */ export function replaceWithMultiple(nodes: Array) { @@ -46,7 +50,11 @@ export function replaceWithMultiple(nodes: Array) { } /** - * Description + * Parse a string as an expression and replace the current node with the result. + * + * NOTE: This is typically not a good idea to use. Building source strings when + * transforming ASTs is an antipattern and SHOULD NOT be encouraged. Even if it's + * easier to use, your transforms will be extremely brittle. */ export function replaceWithSourceString(replacement) { @@ -70,7 +78,7 @@ export function replaceWithSourceString(replacement) { } /** - * Description + * Replace the current node with another. */ export function replaceWith(replacement, whateverAllowed) { @@ -147,7 +155,9 @@ export function replaceWith(replacement, whateverAllowed) { } /** - * Description + * This method takes an array of statements nodes and then explodes it + * into expressions. This method retains completion records which is + * extremely important to retain original semantics. */ export function replaceExpressionWithStatements(nodes: Array) {