invert_axes, invert_xaxis, and invert_yaxis are named and documented in a misleading way

The invert_xaxis and invert_yaxes options, as expected, flip the axes when set to True, so that they go from large to small left to right and down to up, opposite of the conventional bottom left small-number origin.

invert_axes, however, does something different, and for me unexpected – it swaps the x and y axes. The docstrings make it sound like setting invert_axes=True is the same as setting invert_xaxis=True and invert_yaxis=True at the same time:

invert_axes = param.Boolean(default=False, doc="""
    Whether to invert the x- and y-axis""")

invert_xaxis = param.Boolean(default=False, doc="""
    Whether to invert the plot x-axis.""")

invert_yaxis = param.Boolean(default=False, doc="""
    Whether to invert the plot y-axis.""")

(holoviews/plotting/plot.py line 585 to 592)

At a minimum, the docstring for invert_axes should be changed to “Whether to swap the x- and y- axes.” Even clearer would be to rename invert_axes to swap_axes, but I realize this could be a hassle given backwards compatibility requirements.

[jbednar]

I vote for changing invert_axes to swap_axes to avoid confusion, and for not changing invert_xaxis and invert_yaxis, again to avoid confusion (as once we have swap_axes there’s less chance of confusion.

[jlstevens]

Personally, I do like flip a bit more but it is such a mild preference I’m not sure it is worth the confusion that would result from changing it. For holoviews 2.0, I would be very happy for such an API change though.