Merge pull request #3082 from thatneat/patch-1

Clarify documentation for "overlaying"

Author: alexcjohnson

src/plots/cartesian/layout_attributes.js

@@ -687,8 +687,11 @@ module.exports = {
         editType: 'plot',
         description: [
             'If set a same-letter axis id, this axis is overlaid on top of',
-            'the corresponding same-letter axis.',
-            'If *false*, this axis does not overlay any same-letter axes.'
+            'the corresponding same-letter axis, with traces and axes visible for both',
+            'axes.',
+            'If *false*, this axis does not overlay any same-letter axes.',
+            'In this case, for axes with overlapping domains only the highest-numbered',
+            'axis will be visible.'
         ].join(' ')
     },
     layer: {