add some comments to some path methods and remove some dead code

src/babel/transformation/transformer-pass.js

@@ -10,7 +10,6 @@ export default class TransformerPass {
     this.transformer = transformer;
     this.handlers    = transformer.handlers;
     this.file        = file;
-    this.ran         = false;
     this.key         = transformer.key;
   }
 
@@ -21,13 +20,8 @@ export default class TransformerPass {
 
   transform() {
     var file = this.file;
-
     file.log.debug(`Start transformer ${this.key}`);
-
     traverse(file.ast, this.handlers, file.scope, file);
-
     file.log.debug(`Finish transformer ${this.key}`);
-
-    this.ran = true;
   }
 }

src/babel/traversal/path/lib/removal-hooks.js

@@ -2,7 +2,7 @@
 
 import * as t from "../../../types";
 
-// pre hooks should be used for either rejecting removal or delegating removal to a replacement
+// pre hooks should be used for either rejecting removal or delegating removal
 export var pre = [
   function (self) {
     if (self.key === "body" && (self.isBlockStatement() || self.isClassBody())) {

src/babel/traversal/path/resolution.js

@@ -43,6 +43,7 @@ export function resolve(resolved?): ?NodePath {
   // detect infinite recursion
   if (resolved && resolved.indexOf(this) >= 0) return;
 
+  // we store all the paths we've "resolved" in this array to prevent infinite recursion
   resolved = resolved || [];
   resolved.push(this);
 

src/babel/traversal/path/verification.js

@@ -59,7 +59,8 @@ export function matchesPattern(pattern: string, allowPartial?: boolean): boolean
 }
 
 /**
- * Description
+ * Check whether we have the input `key`. If the `key` references an array then we check
+ * if the array has any items, otherwise we just check if it's falsy.
  */
 
 export function has(key): boolean {
@@ -72,15 +73,13 @@ export function has(key): boolean {
 }
 
 /**
- * Description
+ * Alias of `has`.
  */
 
-export function is(key): boolean {
-  return this.has(key);
-}
+export var is = has;
 
 /**
- * Description
+ * Opposite of `has`.
  */
 
 export function isnt(key): boolean {
@@ -88,7 +87,7 @@ export function isnt(key): boolean {
 }
 
 /**
- * Description
+ * Check whether the path node `key` strict equals `value`.
  */
 
 export function equals(key, value): boolean {
@@ -96,7 +95,8 @@ export function equals(key, value): boolean {
 }
 
 /**
- * Description
+ * Check the type against our stored internal type of the node. This is handy when a node has
+ * been removed yet we still internally know the type and need it to calculate node replacement.
  */
 
 export function isPreviousType(type: string): boolean {
@@ -109,8 +109,8 @@ export function isPreviousType(type: string): boolean {
  *   for (KEY in right);
  *   for (KEY;;);
  *
- * This is because these spots allow VariableDeclarations AND normal expressions so we need to tell the
- * path replacement that it's ok to replace this with an expression.
+ * This is because these spots allow VariableDeclarations AND normal expressions so we need
+ * to tell the path replacement that it's ok to replace this with an expression.
  */
 
  export function canHaveVariableDeclarationOrExpression() {
@@ -118,7 +118,7 @@ export function isPreviousType(type: string): boolean {
  }
 
 /**
- * Description
+ * Check whether the current path references a completion record
  */
 
 export function isCompletionRecord() {
@@ -127,10 +127,13 @@ export function isCompletionRecord() {
   do {
     var container = path.container;
 
-    if (path.isFunction()) {
+    // we're in a function so can't be a completion record
+    if (path.isFunctionDeclaration()) {
       return false;
     }
 
+    // check to see if we're the last item in the container and if we are
+    // we're a completion record!
     if (Array.isArray(container) && path.key !== container.length - 1) {
       return false;
     }
@@ -140,7 +143,8 @@ export function isCompletionRecord() {
 }
 
 /**
- * Description
+ * Check whether or not the current `key` allows either a single statement or block statement
+ * so we can explode it if necessary.
  */
 
 export function isStatementOrBlock() {