DOC: numpy.ma.sort and copying behaviour

I started out thinking I’ve found a docbug but I’m becoming less sure. The problem is that the documentation of numpy.ma.sort (devdocs version) says

Sort the array, in-place […] Returns: sorted_array

Whereas the behaviour seems to be the opposite:

>>> import numpy as np
>>> arr = np.arange(5)[::-1]
>>> np.ma.sort(arr)
array([0, 1, 2, 3, 4])
>>> arr
array([4, 3, 2, 1, 0])

The weird thing is that I’ve found https://github.com/numpy/numpy/issues/1966 which suggests that until 2010 the docs had mentioned a copy and the behaviour was mutating, and the docstring was subsequently fixed. However looking at the git blame even in commit 5cb370e923 from 2008 I can see

from numpy import array as narray
# [...]
def sort(...):
    a = narray(a, copy=True, subok=True)

This seems to me that even in 2008 it should have returned a copy, which makes the linked docbug issue very confusing. What am I missing?

Ultimately I think this is a docbug, because np.ma.sort should match np.sort which copies (and is documented as such), whereas the corresponding instance methods should sort in-place.

[eric-wieser]

You could use .split("\n\n", 1)[1] to throw away the first paragraph, which would be less fragile.

Or we could just replace the whole docstring with equivalent to self.copy().sort() or similar, with a link to the other function.

[seberg]

I dunno, I think obviously broken is better than silently outdated. If you wish, add a test or assert mayb.