Add documentation

core/names.js

@@ -29,6 +29,9 @@ goog.provide('Blockly.Names');
 /**
  * Constant to separate developer variable names from user-defined variable
  * names when running generators.
+ * A developer variable will be declared as a global in the generated code, but
+ * will never be shown to the user in the workspace or stored in the variable
+ * map.
  */
 Blockly.Names.DEVELOPER_VARIABLE_TYPE = 'DEVELOPER_VARIABLE';
 
@@ -70,11 +73,24 @@ Blockly.Names.prototype.reset = function() {
   this.variableMap_ = null;
 };
 
+/**
+ * Set the variable map that maps from variable name to variable object.
+ * @param {!Blockly.VariableMap} map The map to track.
+ * @package
+ */
 Blockly.Names.prototype.setVariableMap = function(map) {
   this.variableMap_ = map;
 };
 
-Blockly.Names.prototype.getNameForVariable = function(id) {
+/**
+ * Get the name for a user-defined variable, based on its ID.
+ * This should only be used for variables of type Blockly.Variables.NAME_TYPE.
+ * @param {string} id The ID to look up in the variable map.
+ * @return {?string} The name of the referenced variable, or null if there was
+ *     no variable map or the variable was not found in the map.
+ * @private
+ */
+Blockly.Names.prototype.getNameForUserVariable_ = function(id) {
   if (!this.variableMap_) {
     console.log('Deprecated call to Blockly.Names.prototype.getName without ' +
         'defining a variable map. To fix, add the folowing code in your ' +
@@ -100,7 +116,7 @@ Blockly.Names.prototype.getNameForVariable = function(id) {
  */
 Blockly.Names.prototype.getName = function(name, type) {
   if (type == Blockly.Variables.NAME_TYPE) {
-    var varName = this.getNameForVariable(name);
+    var varName = this.getNameForUserVariable_(name);
     if (varName) {
       name = varName;
     }