talk about 'cliponaxis' in axis 'layer' description and vice-versa

Author: etpinard

src/plots/cartesian/layout_attributes.js

@@ -582,7 +582,9 @@ module.exports = {
             'Sets the layer on which this axis is displayed.',
             'If *above traces*, this axis is displayed above all the subplot\'s traces',
             'If *below traces*, this axis is displayed below all the subplot\'s traces,',
-            'but above the grid lines.'
+            'but above the grid lines.',
+            'Useful when used together with scatter-like traces with `cliponaxis`',
+            'set to *false* to show markers and/or text nodes above this axis.'
         ].join(' ')
     },
     domain: {

src/traces/scatter/attributes.js

@@ -186,7 +186,9 @@ module.exports = {
         editType: 'doplot',
         description: [
             'Determines whether or not markers and text nodes',
-            'are clipped about the subplot axes.'
+            'are clipped about the subplot axes.',
+            'To show markers and text nodes above axis lines and tick labels,',
+            'make sure to set `xaxis.layer` and `yaxis.layer` to *below traces*.'
         ].join(' ')
     },