update generator comments

core/generator.js

@@ -375,15 +375,19 @@ Blockly.Generator.prototype.provideFunction_ = function(desiredName, code) {
 };
 
 /**
- * Hook before code generation starts. Used to initialise the database of variable names.
+ * Hook for code to run before code generation starts.
+ * Subclasses may override this, e.g. to initialise the database of variable
+ * names.
  * @param {!Blockly.Workspace} workspace Workspace to generate code from.
  */
 Blockly.Generator.prototype.init = undefined;
 
 /**
- * Common tasks for generating code from blocks.
- * Handles comments for the specified block and any connected value blocks.
- * Calls any statements following this block.
+ * Common tasks for generating code from blocks.  This is called from
+ * blockToCode and is called on every block, not just top level blocks.
+ * Subclasses may override this, e.g. to generate code for statements following
+ * the block, or to handle comments for the specified block and any connected
+ * value blocks.
  * @param {!Blockly.Block} block The current block.
  * @param {string} code The JavaScript code created for this block.
  * @return {string} JavaScript code with comments and subsequent blocks added.
@@ -392,7 +396,9 @@ Blockly.Generator.prototype.init = undefined;
 Blockly.Generator.prototype.scrub_ = undefined;
 
 /**
- * Hook at end of code generation. Used to prepend the generated code with the variable definitions.
+ * Hook for code to run at end of code generation.
+ * Subclasses may override this, e.g. to prepend the generated code with the
+ * variable definitions.
  * @param {string} code Generated code.
  * @return {string} Completed code.
  */
@@ -400,7 +406,9 @@ Blockly.Generator.prototype.finish = undefined;
 
 /**
  * Naked values are top-level blocks with outputs that aren't plugged into
- * anything.  This is a hook to make line legal for a generator's language.
+ * anything.
+ * Subclasses may override this, e.g. if their language does not allow
+ * naked values.
  * @param {string} line Line of generated code.
  * @return {string} Legal line of code.
  */