Update descriptions to hint at template attributes

Author: camdecoster

src/lib/coerce.js

@@ -240,7 +240,7 @@ exports.valObjectMeta = {
     flaglist: {
         description: [
             'A string representing a combination of flags',
-            '(order does not matter here).',
+            '(flag order does not affect the output).',
             'Combine any of the available `flags` with *+*.',
             "(e.g. ('lines+markers')).",
             'Values in `extras` cannot be combined.'

src/plots/attributes.js

@@ -174,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