added comments and cleaned up code

Author: zfoltz

packages/python/plotly/plotly/basedatatypes.py

@@ -1559,19 +1559,8 @@ def _add_annotation_like(
                         subplot_type=refs[0].subplot_type,
                     )
                 )
-            '''
-            if len(refs) == 1 and secondary_y:
-                raise ValueError(
-                    """
-Cannot add {prop_singular} to secondary y-axis of subplot at position ({r}, {c})
-because subplot does not have a secondary y-axis""".format(
-                        prop_singular=prop_singular, r=row, c=col
-                    )
-                )
-            '''
 
-            #'''
-            # If the new_object was created with an yref specified, the specified yref should be used otherwise assign the xref from the layout_keys
+            # If the new_object was created with an yref specified, the specified yref should be used otherwise assign the xref and yref from the layout_keys
             if new_obj.yref == None or new_obj.yref == "y":
                 if len(refs) == 1 and secondary_y:
                     raise ValueError(
@@ -1582,27 +1571,14 @@ def _add_annotation_like(
                         )
                     )
                 if secondary_y:
-                    yaxis = refs[1].layout_keys[1]
-                    xaxis = refs[1].layout_keys[0]
+                    xaxis, yaxis = refs[1].layout_keys
                 else:
-                    yaxis = refs[0].layout_keys[1]
-                    xaxis = refs[0].layout_keys[0]
-                yref = yaxis.replace("axis", "")
-                xref = xaxis.replace("axis", "")
+                    xaxis, yaxis = refs[0].layout_keys
+                xref, yref = xaxis.replace("axis", ""), yaxis.replace("axis", "")
             else:
                 yref = new_obj.yref
                 xaxis = refs[0].layout_keys[0]
                 xref = xaxis.replace("axis", "")
-            #'''
-
-            """
-            if secondary_y:
-                xaxis, yaxis = refs[1].layout_keys
-            else:
-                xaxis, yaxis = refs[0].layout_keys
-            xref, yref = xaxis.replace("axis", ""), yaxis.replace("axis", "")
-            """
-
             # if exclude_empty_subplots is True, check to see if subplot is
             # empty and return if it is
             if exclude_empty_subplots and (
@@ -1625,8 +1601,9 @@ def _add_domain(ax_letter, new_axref):
 
         self.layout[prop_plural] += (new_obj,)
         # The 'new_obj.xref' and 'new_obj.yref' parameters need to be reset otherwise it
-        # will appear as if user supplied yref params and will force annotation to
-        # be on the axis of the last drawn annotation (they all end up on the same axis)
+        # will appear as if user supplied yref params when looping through subplots and
+        # will force annotation to be on the axis of the last drawn annotation
+        # i.e. they all end up on the same axis.
         new_obj.update(xref=None, yref=None)
 
         return self
@@ -4084,7 +4061,7 @@ def _process_multiple_axis_spanning_shapes(
                 # self.add_{layout_obj} succeeded)
                 # however, in the case of a single plot, xref and yref MAY not be
                 # specified, IF they are not specified we specify them here so the following routines can work
-                # (they need to append " domain" to xref or yref)
+                # (they need to append " domain" to xref or yref). If they are specified, we leave them alone.
                 if self.layout[layout_obj][-1].xref == None:
                     self.layout[layout_obj][-1].update(xref="x")
                 # self.layout[layout_obj][-1].update(xref="x")

packages/python/plotly/plotly/tests/test_core/test_update_objects/test_update_annotations.py

@@ -388,17 +388,19 @@ def test_supplied_yref_on_multi_plot_subplot():
         shared_yaxes=False,
         specs=[[{"secondary_y": True}, {"secondary_y": True}]],
     )
+    ### Add traces to the first subplot
     fig.add_trace(go.Scatter(x=[1, 2, 3], y=[1, 2, 3]), row=1, col=1)
     fig.add_trace(
         go.Scatter(x=[1, 2, 3], y=[3, 2, 1], yaxis="y2"), row=1, col=1, secondary_y=True
     )
+    ### Add traces to the second subplot
     fig.add_trace(go.Scatter(x=[1, 2, 3], y=[1, 2, 3], yaxis="y"), row=1, col=2)
     fig.add_trace(
         go.Scatter(x=[1, 2, 3], y=[1, 1, 2], yaxis="y2"), row=1, col=2, secondary_y=True
     )
-    # add a horizontal line on both subplots secondary y.
-    # When using the subplots.make_subplots() method yref parameter should not be supplied to add_hline()
-    # Instead Secondary_y MUST be True to plot on secondary y
+    # add a horizontal line on both subplots on their respective secondary y.
+    # When using the subplots.make_subplots() method yref parameter should NOT be supplied per docstring instructions.
+    # Instead secondary_y specs and secondary_y parameter MUST be True to plot on secondary y
     fig.add_hline(y=2, row=1, col=1, secondary_y=True)
     fig.add_hline(y=1, row=1, col=2, secondary_y=True)
     assert fig.layout["shapes"][0]["yref"] == "y2"