Documentation – proposal for documentation of svg methods

[mewtaylor]

I was thinking that it might be helpful, since the methods for handling svg drawing are visual, to adopt a coding convention that contextualizes the methods visually in addition to docstrings. These comments could show an example of what the method draws, as well as reference constants/variables used throughout the method spatially/visually for debugging purposes. Here's an example of what I'm kind of thinking of roughly:

/**
 * Render the left edge of the block.
 * @param {!Array.<string>} steps Path of block outline.
 * @param {!Object} connectionsXY Location of block.
 * @param {number} rightEdge Minimum width of block.
 * @private
 *
 *                 __
 * start point -> /
 *                |
 *                 \
 *                  \
 *                   |  <-- Blockly.BlockSvg.NOTCH_HEIGHT
 *                   |
 *                  /
 *                 / 
 *                |
 * end point   -> \__
 */
Blockly.BlockSvg.prototype.renderDrawLeft_ =
    function(steps, connectionsXY, bottom) {
.
.
.
};

Thoughts?

[NeilFraser]

ASCII art rocks.