From 11734a3cf2e09dcc9493f7d48ad41a54266a117e Mon Sep 17 00:00:00 2001
From: thatneat <thatneat@users.noreply.github.com>
Date: Fri, 5 Oct 2018 14:03:36 -0700
Subject: [PATCH] Clarify documentation for "overlaying"

related: #3074
---
 src/plots/cartesian/layout_attributes.js | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/plots/cartesian/layout_attributes.js b/src/plots/cartesian/layout_attributes.js
index 3d81797b7e9..404f023eb71 100644
--- a/src/plots/cartesian/layout_attributes.js
+++ b/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: {