<p dir="auto">The information in <a href="http://www.numpy.org/devdocs/user/c-info.how-to-extend.html#dealing-with-array-objects" rel="nofollow"><code class="notranslate">doc/source/user/c-info.how-to-extend.rst</code></a> is repeated in <a href="http://www.numpy.org/devdocs/reference/c-api.array.html?highlight=pyarray_simplenewfromdata#creating-arrays" rel="nofollow">`doc/source/reference/c-api.array.rst</a>. The first should only reference the second, and the descriptive text should be merged.</p>
<p dir="auto">This may be a good starter task. The cycle to fix this issue, based on the <a href="http://www.numpy.org/devdocs/docs/howto_build_docs.html" rel="nofollow">doc building documentation</a> is to</p>
<ol dir="auto">
<li>create the documentation with <code class="notranslate">make html</code></li>
<li>Note the many warnings about <code class="notranslate">duplicate C object description</code> in the two files</li>
<li>Edit the files to unify the documentation, one should be using <code class="notranslate">.. c:function::</code> to define the functions and the other using <code class="notranslate">:c:func:</code> to reference it, perhaps with descriptive text.</li>
<li>Use <code class="notranslate">firefox build/html/reference/c-api.array.html</code> and <code class="notranslate">firefox build/html/user/c-info.how-to-extend.html</code> to view the changes</li>
</ol>
<p dir="auto">I started out thinking I've found a docbug but I'm becoming less sure. The problem is that <a href="https://docs.scipy.org/doc/numpy/reference/generated/numpy.ma.sort.html" rel="nofollow">the documentation of <code class="notranslate">numpy.ma.sort</code></a> (<a href="https://numpy.org/devdocs/reference/generated/numpy.ma.sort.html#numpy.ma.sort" rel="nofollow">devdocs version</a>) says</p>
<blockquote>
<p dir="auto">Sort the array, in-place<br>
[...]<br>
Returns: <code class="notranslate">sorted_array</code></p>
</blockquote>
<p dir="auto">Whereas the behaviour seems to be the opposite:</p>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&gt;&gt;&gt; import numpy as np
&gt;&gt;&gt; arr = np.arange(5)[::-1]
&gt;&gt;&gt; np.ma.sort(arr)
array([0, 1, 2, 3, 4])
&gt;&gt;&gt; arr
array([4, 3, 2, 1, 0])"><pre class="notranslate"><span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-k">import</span> <span class="pl-s1">numpy</span> <span class="pl-k">as</span> <span class="pl-s1">np</span>
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">arr</span> <span class="pl-c1">=</span> <span class="pl-s1">np</span>.<span class="pl-en">arange</span>(<span class="pl-c1">5</span>)[::<span class="pl-c1">-</span><span class="pl-c1">1</span>]
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">np</span>.<span class="pl-s1">ma</span>.<span class="pl-en">sort</span>(<span class="pl-s1">arr</span>)
<span class="pl-en">array</span>([<span class="pl-c1">0</span>, <span class="pl-c1">1</span>, <span class="pl-c1">2</span>, <span class="pl-c1">3</span>, <span class="pl-c1">4</span>])
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">arr</span>
<span class="pl-en">array</span>([<span class="pl-c1">4</span>, <span class="pl-c1">3</span>, <span class="pl-c1">2</span>, <span class="pl-c1">1</span>, <span class="pl-c1">0</span>])</pre></div>
<p dir="auto">The weird thing is that I've found <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="7729142" data-permission-text="Title is private" data-url="https://github.com/numpy/numpy/issues/1966" data-hovercard-type="issue" data-hovercard-url="/numpy/numpy/issues/1966/hovercard" href="https://github.com/numpy/numpy/issues/1966">#1966</a> 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 <a href="https://github.com/numpy/numpy/blob/5cb370e9234582f62231384c26a426301dad3331/numpy/ma/core.py#L2859">in commit 5cb370e923 from 2008</a> I can see</p>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="from numpy import array as narray
# [...]
def sort(...):
    a = narray(a, copy=True, subok=True)"><pre class="notranslate"><span class="pl-k">from</span> <span class="pl-s1">numpy</span> <span class="pl-k">import</span> <span class="pl-s1">array</span> <span class="pl-k">as</span> <span class="pl-s1">narray</span>
<span class="pl-c"># [...]</span>
<span class="pl-k">def</span> <span class="pl-en">sort</span>(...):
    <span class="pl-s1">a</span> <span class="pl-c1">=</span> <span class="pl-en">narray</span>(<span class="pl-s1">a</span>, <span class="pl-s1">copy</span><span class="pl-c1">=</span><span class="pl-c1">True</span>, <span class="pl-s1">subok</span><span class="pl-c1">=</span><span class="pl-c1">True</span>)</pre></div>
<p dir="auto">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?</p>
<p dir="auto">Ultimately I think this is a docbug, because <code class="notranslate">np.ma.sort</code> should match <code class="notranslate">np.sort</code> which copies (and is documented as such), whereas the corresponding instance methods should sort in-place.</p>