docs: Add template hints to attribute descriptions

src/plots/attributes.js

@@ -6,7 +6,7 @@ var fxAttrs = require('../components/fx/attributes');
 module.exports = {
     type: {
         valType: 'enumerated',
-        values: [],     // listed dynamically
+        values: [], // listed dynamically
         dflt: 'scatter',
         editType: 'calc+clearAxisTypes',
         _noTemplating: true // we handle this at a higher level
@@ -27,10 +27,9 @@ module.exports = {
         valType: 'boolean',
         dflt: true,
         editType: 'style',
-        description: [
-            'Determines whether or not an item corresponding to this',
-            'trace is shown in the legend.'
-        ].join(' ')
+        description: ['Determines whether or not an item corresponding to this', 'trace is shown in the legend.'].join(
+            ' '
+        )
     },
     legend: {
         valType: 'subplotid',
@@ -59,17 +58,13 @@ module.exports = {
             valType: 'string',
             dflt: '',
             editType: 'style',
-            description: [
-                'Sets the title of the legend group.'
-            ].join(' ')
+            description: ['Sets the title of the legend group.'].join(' ')
         },
         font: fontAttrs({
             editType: 'style',
-            description: [
-                'Sets this legend group\'s title font.'
-            ].join(' '),
+            description: ["Sets this legend group's title font."].join(' ')
         }),
-        editType: 'style',
+        editType: 'style'
     },
     legendrank: {
         valType: 'number',
@@ -90,7 +85,7 @@ module.exports = {
         valType: 'number',
         min: 0,
         editType: 'style',
-        description: 'Sets the width (in px or fraction) of the legend for this trace.',
+        description: 'Sets the width (in px or fraction) of the legend for this trace.'
     },
     opacity: {
         valType: 'number',
@@ -103,10 +98,7 @@ module.exports = {
     name: {
         valType: 'string',
         editType: 'style',
-        description: [
-            'Sets the trace name.',
-            'The trace name appears as the legend item and on hover.'
-        ].join(' ')
+        description: ['Sets the trace name.', 'The trace name appears as the legend item and on hover.'].join(' ')
     },
     uid: {
         valType: 'string',
@@ -182,7 +174,7 @@ module.exports = {
         dflt: 'all',
         editType: 'none',
         description: [
-            'Determines which trace information appear on hover.',
+            'Determines what trace information appears on hover.',
             'If `none` or `skip` are set, no information is displayed upon hovering.',
             'But, if `none` is set, click and hover events are still fired.'
         ].join(' ')

src/traces/funnel/attributes.js

@@ -41,9 +41,12 @@ module.exports = {
         editType: 'plot',
         arrayOk: false,
         description: [
-            'Determines which trace information appear on the graph.',
+            'Determines what trace information appears on the graph.',
             'In the case of having multiple funnels, percentages & totals',
-            'are computed separately (per trace).'
+            'are computed separately (per trace).',
+            'Flags are rendered in a fixed order; use `texttemplate` if you',
+            'need explicit control over the rendered string, including the',
+            'order of fields and surrounding text.'
         ].join(' ')
     },
     // TODO: incorporate `label` and `value` in the eventData

src/traces/funnelarea/attributes.js

@@ -50,7 +50,13 @@ module.exports = {
     texttemplatefallback: templatefallbackAttrs({ editType: 'plot' }),
 
     hoverinfo: extendFlat({}, baseAttrs.hoverinfo, {
-        flags: ['label', 'text', 'value', 'percent', 'name']
+        flags: ['label', 'text', 'value', 'percent', 'name'],
+        description: [
+            'Determines what trace information appears on hover.',
+            'Flags are rendered in a fixed order; use `hovertemplate` if you',
+            'need explicit control over the rendered string, including the',
+            'order of fields and surrounding text.'
+        ].join(' ')
     }),
 
     hovertemplate: hovertemplateAttrs({}, { keys: ['label', 'color', 'value', 'text', 'percent'] }),

src/traces/pie/attributes.js

@@ -133,10 +133,21 @@ module.exports = {
         flags: ['label', 'text', 'value', 'percent'],
         extras: ['none'],
         editType: 'calc',
-        description: ['Determines which trace information appear on the graph.'].join(' ')
+        description: [
+            'Determines what trace information appears on the graph.',
+            'Flags are rendered in a fixed order; use `texttemplate` if you',
+            'need explicit control over the rendered string, including the',
+            'order of fields and surrounding text.'
+        ].join(' ')
     },
     hoverinfo: extendFlat({}, baseAttrs.hoverinfo, {
-        flags: ['label', 'text', 'value', 'percent', 'name']
+        flags: ['label', 'text', 'value', 'percent', 'name'],
+        description: [
+            'Determines what trace information appears on hover.',
+            'Flags are rendered in a fixed order; use `hovertemplate` if you',
+            'need explicit control over the rendered string, including the',
+            'order of fields and surrounding text.'
+        ].join(' ')
     }),
     hovertemplate: hovertemplateAttrs({}, { keys: ['label', 'color', 'value', 'percent', 'text'] }),
     hovertemplatefallback: templatefallbackAttrs(),

src/traces/sankey/attributes.js

@@ -19,7 +19,7 @@ var attrs = (module.exports = overrideAll(
             flags: [],
             arrayOk: false,
             description: [
-                'Determines which trace information appear on hover.',
+                'Determines what trace information appears on hover.',
                 'If `none` or `skip` are set, no information is displayed upon hovering.',
                 'But, if `none` is set, click and hover events are still fired.',
                 'Note that this attribute is superseded by `node.hoverinfo` and `node.hoverinfo`',
@@ -150,7 +150,7 @@ var attrs = (module.exports = overrideAll(
                 values: ['all', 'none', 'skip'],
                 dflt: 'all',
                 description: [
-                    'Determines which trace information appear when hovering nodes.',
+                    'Determines what trace information appears when hovering nodes.',
                     'If `none` or `skip` are set, no information is displayed upon hovering.',
                     'But, if `none` is set, click and hover events are still fired.'
                 ].join(' ')
@@ -242,7 +242,7 @@ var attrs = (module.exports = overrideAll(
                 values: ['all', 'none', 'skip'],
                 dflt: 'all',
                 description: [
-                    'Determines which trace information appear when hovering links.',
+                    'Determines what trace information appears when hovering links.',
                     'If `none` or `skip` are set, no information is displayed upon hovering.',
                     'But, if `none` is set, click and hover events are still fired.'
                 ].join(' ')

src/traces/sunburst/attributes.js

@@ -138,7 +138,12 @@ module.exports = {
         flags: ['label', 'text', 'value', 'current path', 'percent root', 'percent entry', 'percent parent'],
         extras: ['none'],
         editType: 'plot',
-        description: ['Determines which trace information appear on the graph.'].join(' ')
+        description: [
+            'Determines what trace information appears on the graph.',
+            'Flags are rendered in a fixed order; use `texttemplate` if you',
+            'need explicit control over the rendered string, including the',
+            'order of fields and surrounding text.'
+        ].join(' ')
     },
 
     // TODO: incorporate `label` and `value` in the eventData
@@ -148,7 +153,13 @@ module.exports = {
     hovertext: pieAttrs.hovertext,
     hoverinfo: extendFlat({}, baseAttrs.hoverinfo, {
         flags: ['label', 'text', 'value', 'name', 'current path', 'percent root', 'percent entry', 'percent parent'],
-        dflt: 'label+text+value+name'
+        dflt: 'label+text+value+name',
+        description: [
+            'Determines what trace information appears on hover.',
+            'Flags are rendered in a fixed order; use `hovertemplate` if you',
+            'need explicit control over the rendered string, including the',
+            'order of fields and surrounding text.'
+        ].join(' ')
     }),
     hovertemplate: hovertemplateAttrs({}, { keys: constants.eventDataKeys }),
     hovertemplatefallback: templatefallbackAttrs(),

src/traces/waterfall/attributes.js

@@ -89,9 +89,12 @@ module.exports = {
         editType: 'plot',
         arrayOk: false,
         description: [
-            'Determines which trace information appear on the graph.',
+            'Determines what trace information appears on the graph.',
             'In the case of having multiple waterfalls, totals',
-            'are computed separately (per trace).'
+            'are computed separately (per trace).',
+            'Flags are rendered in a fixed order; use `texttemplate` if you',
+            'need explicit control over the rendered string, including the',
+            'order of fields and surrounding text.'
         ].join(' ')
     },
     // TODO: incorporate `label` and `value` in the eventData