Formatting and comments for state.js

lib/state.js

@@ -27,6 +27,7 @@ var util = require('util');
 
 var StatusMessage = require('./apiclasses.js').StatusMessage;
 
+// Error message indices into the resolved variable table.
 var BUFFER_FULL_MESSAGE_INDEX = 0;
 var NATIVE_PROPERTY_MESSAGE_INDEX = 1;
 var GETTER_MESSAGE_INDEX = 2;
@@ -48,15 +49,20 @@ MESSAGE_TABLE[ARG_LOCAL_LIMIT_MESSAGE_INDEX] =
                               'top `config.capture.maxExpandFrames` stack frames.',
                                 true) };
 
-// TODO: document this file
-
-// returns an object with three fields: stacksframes,
-// variableTable and evaluated_expressions
+/**
+ * Captures the stack and current execution state.
+ *
+ * @return an object with stackFrames, variableTable, and
+ *         evaluatedExpressions fields
+ */
 function capture(execState, expressions, config) {
-  return (new StateResolver(execState, expressions, config)).capture();
+  return (new StateResolver(execState, expressions, config)).capture_();
 }
 
+
 /**
+ * Checks that the provided expressions will not have side effects and
+ * then evaluates the expression in the current execution context.
  *
  * @return an object with error and mirror fields.
  */
@@ -87,6 +93,7 @@ function evaluate(expression, frame) {
   }
 }
 
+
 /**
  * @param {!Object} execState
  * @param {Array<string>} expressions
@@ -106,7 +113,13 @@ function StateResolver(execState, expressions, config) {
 }
 
 
-StateResolver.prototype.capture = function() {
+/**
+ * Captures the stack and current execution state.
+ *
+ * @return an object with stackFrames, variableTable, and
+ *         evaluatedExpressions fields
+ */
+StateResolver.prototype.capture_ = function() {
   // Gather the stack frames first
   var that = this;
   var frames = that.resolveFrames_();
@@ -140,9 +153,6 @@ StateResolver.prototype.capture = function() {
     index++;
   }
 
-  // console.log('totalSize: ' + that.totalSize_ + ' index: ' + index + ' table: '+
-  //   that.rawVariableTable_.length);
-
   // If we filled up the buffer already, we need to trim the remainder
   if (index < that.rawVariableTable_.length) {
     that.trimVariableTable_(index, frames);
@@ -155,6 +165,15 @@ StateResolver.prototype.capture = function() {
   };
 };
 
+/**
+ * Limits the size of the variable table to `fromIndex` elements. It marks
+ * all variables with entries beyond `fromIndex` with a message indicating
+ * that the table filled.
+ *
+ * @param {Number} fromIndex The desired size of the variable table.
+ * @param {Object} frames Frames associated with the current execution
+ *                        environment.
+ */
 StateResolver.prototype.trimVariableTable_ = function(fromIndex, frames) {
   this.resolvedVariableTable_.splice(fromIndex); // remove the remaining entries
 
@@ -194,7 +213,6 @@ StateResolver.prototype.resolveFrames_ = function() {
   return frames;
 };
 
-
 StateResolver.prototype.shouldFrameBeResolved_ = function(frame) {
   // Only capture data from the frames for which we can link the data back
   // to the source files.
@@ -214,7 +232,6 @@ StateResolver.prototype.shouldFrameBeResolved_ = function(frame) {
   return true;
 };
 
-
 StateResolver.prototype.resolveFullPath_ = function(frame) {
   var func = frame.func();
   if (!func.resolved()) {
@@ -229,30 +246,25 @@ StateResolver.prototype.resolveFullPath_ = function(frame) {
   return script.name();
 };
 
-
 StateResolver.prototype.resolveRelativePath_ = function(frame) {
   var fullPath = this.resolveFullPath_(frame);
   return this.stripCurrentWorkingDirectory_(fullPath);
 };
 
-
 StateResolver.prototype.stripCurrentWorkingDirectory_ = function(path) {
   // Strip 1 extra character to remove the slash.
   return path.substr(this.config_.workingDirectory.length + 1);
 };
 
-
 StateResolver.prototype.isPathInCurrentWorkingDirectory_ = function(path) {
   //return true;
   return path.indexOf(this.config_.workingDirectory) === 0;
 };
 
-
 StateResolver.prototype.isPathInNodeModulesDirectory_ = function(path) {
   return path.indexOf('node_modules') === 0;
 };
 
-
 StateResolver.prototype.resolveFrame_ = function(frame, resolveVars) {
   var args = resolveVars ? this.resolveArgumentList_(frame) : [{
     name: 'arguments_not_available',
@@ -270,15 +282,13 @@ StateResolver.prototype.resolveFrame_ = function(frame, resolveVars) {
   };
 };
 
-
 StateResolver.prototype.resolveFunctionName_ = function(func) {
   if (!func || !func.isFunction()) {
     return '';
   }
   return func.name() || func.inferredName() || '(anonymous function)';
 };
 
-
 StateResolver.prototype.resolveLocation_ = function(frame) {
   return {
     path: this.resolveRelativePath_(frame),
@@ -287,7 +297,6 @@ StateResolver.prototype.resolveLocation_ = function(frame) {
   };
 };
 
-
 StateResolver.prototype.resolveArgumentList_ = function(frame) {
   var args = [];
   for (var i = 0; i < frame.argumentCount(); i++) {
@@ -301,7 +310,6 @@ StateResolver.prototype.resolveArgumentList_ = function(frame) {
   return args;
 };
 
-
 StateResolver.prototype.resolveLocalsList_ = function(frame,
     resolvedArguments) {
   var locals = [];
@@ -321,7 +329,14 @@ StateResolver.prototype.resolveLocalsList_ = function(frame,
   return locals;
 };
 
-
+/**
+ * Computes a text representation of the provided value based on its type.
+ * If the value is a recursive data type, it will be represented as an index
+ * into the variable table.
+ *
+ * @param {String} name The name of the variable.
+ * @param {Object} value A v8 debugger representation of a variable value.
+ */
 StateResolver.prototype.resolveVariable_ = function(name, value) {
   var size = name.length;
 
@@ -367,13 +382,20 @@ StateResolver.prototype.getVariableIndex_ = function(value) {
   return idx;
 };
 
-
 StateResolver.prototype.storeObjectToVariableTable_ = function(obj) {
   var idx = this.rawVariableTable_.length;
   this.rawVariableTable_[idx] = obj;
   return idx;
 };
 
+/**
+ * Responsible for recursively resolving the properties on a
+ * provided object mirror. Due to a bug in early node versions,
+ * we maintain two implementations using the fast approach
+ * for supported node versions.
+ *
+ * See https://github.com/iojs/io.js/issues/1190.
+ */
 StateResolver.prototype.resolveMirror_ = function(mirror) {
   if (semver.satisfies(process.version, '<1.6')) {
     return this.resolveMirrorSlow_(mirror);
@@ -383,8 +405,6 @@ StateResolver.prototype.resolveMirror_ = function(mirror) {
 };
 
 // A slower implementation of resolveMirror_ which is safe for all node versions
-//
-// See https://github.com/iojs/io.js/issues/1190.
 StateResolver.prototype.resolveMirrorSlow_ = function(mirror) {
   // Instead, let's use Object.keys. This will only get the enumerable
   // properties. The other alternative would be Object.getOwnPropertyNames, but
@@ -415,12 +435,14 @@ StateResolver.prototype.resolveMirrorFast_ = function(mirror) {
     members: members
   };
 };
+
 StateResolver.prototype.getMirrorProperties_ = function(mirror) {
   var numProperties = this.config_.capture.maxProperties;
   var namedProperties = mirror.properties(1, numProperties);
   var indexedProperties = mirror.properties(2, numProperties);
   return namedProperties.concat(indexedProperties);
 };
+
 StateResolver.prototype.resolveMirrorProperty_ = function(property) {
   if (property.isNative()) {
     return {