add more comments to path methods

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<NodePath>, 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() {

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() {

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) {

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() {

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<Object>) {
@@ -46,7 +50,11 @@ export function replaceWithMultiple(nodes: Array<Object>) {
 }
 
 /**
- * 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) {