diff --git a/src/traces/mesh3d/attributes.js b/src/traces/mesh3d/attributes.js
index d941e75b77a..d800707bbdd 100644
--- a/src/traces/mesh3d/attributes.js
+++ b/src/traces/mesh3d/attributes.js
@@ -8,122 +8,122 @@
 
 
 var colorscaleAttrs = require('../../components/colorscale/attributes');
+var surfaceAtts = require('../surface/attributes');
+var extendFlat = require('../../lib/extend').extendFlat;
+
 
 module.exports = {
-    x: {valType: 'data_array'},
-    y: {valType: 'data_array'},
-    z: {valType: 'data_array'},
+    x: {
+        valType: 'data_array',
+        description: 'Sets the x coordinates of the vertices'
+    },
+    y: {
+        valType: 'data_array',
+        description: 'Sets the y coordinates of the vertices'
+    },
+    z: {
+        valType: 'data_array',
+        description: 'Sets the z coordinates of the vertices'
+    },
 
-    i: {valType: 'data_array'},
-    j: {valType: 'data_array'},
-    k: {valType: 'data_array'},
+    i: {
+        valType: 'data_array',
+        description: 'Sets the indices of x coordinates of the vertices'
+    },
+    j: {
+        valType: 'data_array',
+        description: 'Sets the indices of y coordinates of the vertices'
+    },
+    k: {
+        valType: 'data_array',
+        description: 'Sets the indices of z coordinates of the vertices'
+    },
 
     delaunayaxis: {
-      valType: 'enumerated',
-      role: 'info',
-      values: [ 'x', 'y', 'z' ],
-      dflt: 'z'
+        valType: 'enumerated',
+        role: 'info',
+        values: [ 'x', 'y', 'z' ],
+        dflt: 'z',
+        description: [
+            'Sets the Delaunay axis from which the triangulation of the mesh',
+            'takes place.',
+            'An alternative to setting the `i`, `j`, `k` indices triplets.'
+        ].join(' ')
     },
 
     alphahull: {
-      valType: 'number',
-      role: 'style',
-      dflt: -1
+        valType: 'number',
+        role: 'style',
+        dflt: -1,
+        description: [
+            'Sets the shape of the mesh',
+            'If *-1*, Delaunay triangulation is used',
+            'If *>0*, the alpha-shape algorithm is used',
+            'If *0*,  the convex-hull algorithm is used',
+            'An alternative to the `i`, `j`, `k` indices triplets.'
+        ].join(' ')
     },
 
-    intensity: {valType: 'data_array'},
+    intensity: {
+        valType: 'data_array',
+        description: [
+            'Sets the vertex intensity values,',
+            'used for plotting fields on meshes'
+        ].join(' ')
+    },
 
     //Color field
     color: {
         valType: 'color',
-        role: 'style'
+        role: 'style',
+        description: 'Sets the color of the whole mesh'
     },
     vertexcolor: {
         valType: 'data_array',  // FIXME: this should be a color array
-        role: 'style'
+        role: 'style',
+        description: [
+            'Sets the color of each vertex',
+            'Overrides *color*.'
+        ].join(' ')
     },
     facecolor: {
         valType: 'data_array',
-        role: 'style'
+        role: 'style',
+        description: [
+            'Sets the color of each face',
+            'Overrides *color* and *vertexcolor*.'
+        ].join(' ')
     },
 
     //Opacity
-    opacity: {
-        valType: 'number',
-        role: 'style',
-        min: 0,
-        max: 1,
-        dflt: 1
-    },
+    opacity: extendFlat({}, surfaceAtts.opacity),
 
     //Flat shaded mode
     flatshading: {
         valType: 'boolean',
         role: 'style',
-        dflt: false
+        dflt: false,
+        description: [
+            'Determines whether or not normal smoothing is applied to the meshes,',
+            'creating meshes with a low-poly look.'
+        ].join(' ')
     },
 
     contour: {
-        show: {
-            valType: 'boolean',
-            role: 'info',
-            dflt: false
-        },
-        color: {
-            valType: 'color',
-            role: 'style',
-            dflt: '#000'
-        },
-        width: {
-            valType: 'number',
-            role: 'style',
-            min: 1,
-            max: 16,
-            dflt: 2
-        }
+        show: extendFlat({}, surfaceAtts.contours.x.show, {
+            description: [
+                'Sets whether or not dynamic contours are shown on hover'
+            ].join(' ')
+        }),
+        color: extendFlat({}, surfaceAtts.contours.x.color),
+        width: extendFlat({}, surfaceAtts.contours.x.width)
     },
 
     colorscale: colorscaleAttrs.colorscale,
     reversescale: colorscaleAttrs.reversescale,
     showscale: colorscaleAttrs.showscale,
 
-    lighting: {
-        ambient: {
-            valType: 'number',
-            role: 'style',
-            min: 0.00,
-            max: 1.0,
-            dflt: 0.8
-        },
-        diffuse: {
-            valType: 'number',
-            role: 'style',
-            min: 0.00,
-            max: 1.00,
-            dflt: 0.8
-        },
-        specular: {
-            valType: 'number',
-            role: 'style',
-            min: 0.00,
-            max: 2.00,
-            dflt: 0.05
-        },
-        roughness: {
-            valType: 'number',
-            role: 'style',
-            min: 0.00,
-            max: 1.00,
-            dflt: 0.5
-        },
-        fresnel: {
-            valType: 'number',
-            role: 'style',
-            min: 0.00,
-            max: 5.00,
-            dflt: 0.2
-        }
-    },
+    lighting: extendFlat({}, surfaceAtts.lighting),
 
     _nestedModules: {  // nested module coupling
         'colorbar': 'Colorbar'
diff --git a/src/traces/mesh3d/index.js b/src/traces/mesh3d/index.js
index 6cdc651029c..d81cf6bc8b9 100644
--- a/src/traces/mesh3d/index.js
+++ b/src/traces/mesh3d/index.js
@@ -15,7 +15,12 @@ var Mesh3D = module.exports = {};
 
 Plotly.Plots.register(Mesh3D, 'mesh3d', ['gl3d'], {
     description: [
-        ''
+        'Draws sets of triangles with coordinates given by',
+        'three 1-dimensional arrays in `x`, `y`, `z` and',
+        '(1) a sets of `i`, `j`, `k` indices',
+        '(2) Delaunay triangulation or',
+        '(3) the Alpha-shape algorithm or',
+        '(4) the Convex-hull algorithm'
     ].join(' ')
 });