DOC: error in 0.23.0 concat sort warning?

[adbull]

Problem description

Pandas 0.23.0 adds a new warning when calling concat with misaligned axes (#20613):

FutureWarning: Sorting because non-concatenation axis is not aligned. A future version
of pandas will change to not sort by default.

To accept the future behavior, pass 'sort=True'.

To retain the current behavior and silence the warning, pass sort=False

This seems strange; I'd assume that sort=True would give the current behaviour, and sort=False the future behaviour, as in the docs for concat:

Explicitly pass sort=True to silence the warning and sort. Explicitly pass
sort=False to silence the warning and not sort.

I'm assuming the docs are right and the warning is wrong?

[TomAugspurger]

Whoops, you're correct. Mind making a PR to fix it? May have to update a test or two.

[TomAugspurger]

To clarify a bit (using the example from #21174)

>>> df = pd.DataFrame({"a": [1, 2], "b": [1, 2]}, columns=['b', 'a'])

The warning only appears when the non-concatenation axis is not already aligned and sort is not explicitly passed.

In [12]: df1 = pd.DataFrame(1, index=[0, 1], columns=['b', 'a'])

In [13]: df2 = pd.DataFrame(1, index=[0, 1], columns=['b', 'A'])

In [14]: pd.concat([df1, df2])
/Users/taugspurger/.virtualenvs/dask-dev/bin/ipython:1: FutureWarning: Sorting because non-concatenation axis is not aligned. A future version
of pandas will change to not sort by default.

To accept the future behavior, pass 'sort=True'.

To retain the current behavior and silence the warning, pass sort=False

  #!/Users/taugspurger/Envs/dask-dev/bin/python3
Out[14]:
     A    a  b
0  NaN  1.0  1
1  NaN  1.0  1
0  1.0  NaN  1
1  1.0  NaN  1

The message saying how to achieve the future / current behavior is wrong. It should be

- To accept the future behavior, pass 'sort=False'.
- To accept the current behavior and silence the warning, pass 'sort=True'