improve surface attribute descriptions

Author: etpinard

src/traces/surface/attributes.js

@@ -98,8 +98,8 @@ module.exports = {
     surfacecolor: {
         valType: 'data_array',
         description: [
-            'Sets the surface intensity values,',
-            'used for setting a color scale independent of z'
+            'Sets the surface color values,',
+            'used for setting a color scale independent of `z`.'
         ].join(' ')
     },
     cauto: colorscaleAttrs.zauto,
@@ -171,8 +171,14 @@ module.exports = {
     },
 
     _deprecated: {
-        zauto: colorscaleAttrs.zauto,
-        zmin: colorscaleAttrs.zmin,
-        zmax: colorscaleAttrs.zmax
+        zauto: extendFlat({}, colorscaleAttrs.zauto, {
+            description: 'Obsolete. Use `cauto` instead.'
+        }),
+        zmin: extendFlat({}, colorscaleAttrs.zmin, {
+            description: 'Obsolete. Use `cmin` instead.'
+        }),
+        zmax: extendFlat({}, colorscaleAttrs.zmax, {
+            description: 'Obsolete. Use `cmax` instead.'
+        })
     }
 };

src/traces/surface/index.js

@@ -30,7 +30,11 @@ Surface.meta = {
         'or {2D arrays} (e.g. to graph parametric surfaces).',
 
         'If not provided in `x` and `y`, the x and y coordinates are assumed',
-        'to be linear starting at 0 with a unit step.'
+        'to be linear starting at 0 with a unit step.',
+
+        'The color scale corresponds to the `z` values by default.',
+        'For custom color scales, use `surfacecolor` which should be a {2D array},',
+        'where its bounds can be controlled using `cmin` and `cmax`.'
     ].join(' ')
 };