rename some functions/variables, add comments, improve docstrings

Author: emilykl

src/components/shapes/attributes.js

@@ -4,7 +4,7 @@ var annAttrs = require('../annotations/attributes');
 var fontAttrs = require('../../plots/font_attributes');
 var scatterLineAttrs = require('../../traces/scatter/attributes').line;
 var dash = require('../drawing/attributes').dash;
-var templateFormatStringDescription = require('../../plots/template_attributes').templateFormatStringDescription;
+var templateFormatStringDescriptionForShapes = require('../../plots/template_attributes').templateFormatStringDescriptionForShapes;
 var describeVariables = require('../../plots/template_attributes').describeVariables;
 var extendFlat = require('../../lib/extend').extendFlat;
 var templatedArray = require('../../plot_api/plot_template').templatedArray;
@@ -241,7 +241,7 @@ module.exports = templatedArray('shape', {
             description: [
                 'Template string used for rendering the shape\'s label.',
                 'Note that this will override `text`.',
-                templateFormatStringDescription(),
+                templateFormatStringDescriptionForShapes(),
                 describeVariables(['x0', 'y0', 'x1', 'y1', 'slope']),
             ].join(' ')
         },

src/components/shapes/draw.js

@@ -611,7 +611,7 @@ function drawLabel(gd, index, options, shapeGroup) {
     // Text template overrides text
     var text = options.label.text;
     if(options.label.texttemplate) {
-        text = Lib.texttemplateStringWithMath(options.label.texttemplate,
+        text = Lib.texttemplateStringForShapes(options.label.texttemplate,
             {},
             gd._fullLayout._d3locale,
             {

src/components/shapes/draw_newshape/attributes.js

@@ -2,7 +2,7 @@
 
 var fontAttrs = require('../../../plots/font_attributes');
 var dash = require('../../drawing/attributes').dash;
-var templateFormatStringDescription = require('../../../plots/template_attributes').templateFormatStringDescription;
+var templateFormatStringDescriptionForShapes = require('../../../plots/template_attributes').templateFormatStringDescriptionForShapes;
 var describeVariables = require('../../../plots/template_attributes').describeVariables;
 var extendFlat = require('../../../lib/extend').extendFlat;
 
@@ -95,7 +95,7 @@ module.exports = {
                 description: [
                     'Template string used for rendering the new shape\'s label.',
                     'Note that this will override `text`.',
-                    templateFormatStringDescription(),
+                    templateFormatStringDescriptionForShapes(),
                     describeVariables(['x0', 'y0', 'x1', 'y1', 'slope']),
                 ].join(' ')
             },

src/lib/index.js

@@ -1074,20 +1074,24 @@ lib.texttemplateString = function() {
     return templateFormatString.apply(texttemplateWarnings, arguments);
 };
 
+// Regex for parsing multiplication and division operations applied to a template key
+// Used for shape.label.texttemplate
+// Matches a key name (non-whitespace characters), followed by a * or / character, followed by a number
+// For example, the following strings are matched: `x0*2`, `slope/1.60934`, `y1*2.54`
 var MULT_DIV_REGEX = /^(\S+)([\*\/])(-?\d+(\.\d+)?)$/;
-function parseMultDiv(inputStr) {
+function multDivParser(inputStr) {
     var match = inputStr.match(MULT_DIV_REGEX);
     if(match) return { key: match[1], op: match[2], number: Number(match[3]) };
     else return { key: inputStr, op: null, number: null };
 }
-var texttemplateWarningsWithMath = {
+var texttemplateWarningsForShapes = {
     max: 10,
     count: 0,
     name: 'texttemplate',
-    parseMath: true,
+    parseMultDiv: true,
 };
-lib.texttemplateStringWithMath = function() {
-    return templateFormatString.apply(texttemplateWarningsWithMath, arguments);
+lib.texttemplateStringForShapes = function() {
+    return templateFormatString.apply(texttemplateWarningsForShapes, arguments);
 };
 
 var TEMPLATE_STRING_FORMAT_SEPARATOR = /^[:|\|]/;
@@ -1139,10 +1143,11 @@ function templateFormatString(string, labels, d3locale) {
         if(isOtherSpace || isSpaceOtherSpace) key = key.substring(0, key.length - 1);
 
         // Shape labels support * and / operators in template string
+        // Parse these if the parseMultDiv param is set to true
         var parsedOp = null;
         var parsedNumber = null;
-        if(opts.parseMath) {
-            var _match = parseMultDiv(key);
+        if(opts.parseMultDiv) {
+            var _match = multDivParser(key);
             key = _match.key;
             parsedOp = _match.op;
             parsedNumber = _match.number;
@@ -1171,6 +1176,7 @@ function templateFormatString(string, labels, d3locale) {
             }
         }
 
+        // Apply mult/div operation (if applicable)
         if(parsedOp) {
             value = {
                 '*': (function(v) { return v * parsedNumber; }),

src/plots/template_attributes.js

@@ -22,7 +22,19 @@ function templateFormatStringDescription(opts) {
         'for details on the date formatting syntax.'
     ].join(' ');
 }
-exports.templateFormatStringDescription = templateFormatStringDescription;
+
+function templateFormatStringDescriptionForShapes() {
+    return [
+        'Variables are inserted using %{variable},',
+        'for example "x0: %{x0}".',
+        'Numbers are formatted using d3-format\'s syntax %{variable:d3-format}, for example "Price: %{x0:$.2f}".',
+        FORMAT_LINK,
+        'for details on the formatting syntax.',
+        'A single multiplication or division operation may be applied to the variable, and combined with',
+        'd3 number formatting, for example "Length in cm: %{x0*2.54}", "%{slope*60:.1f} meters per second."'
+    ].join(' ');
+}
+exports.templateFormatStringDescriptionForShapes = templateFormatStringDescriptionForShapes;
 
 function describeVariables(extra) {
     var descPart = extra.description ? ' ' + extra.description : '';