[SciPy-dev] Code refactoring can result in loss of documentation

[Scott Sinclair]

I noticed yesterday that when Pierre GM fixed ticket #961
(http://scipy.org/scipy/numpy/ticket/961), the revised docstrings for
np.ma.getdata and np.ma.getmask in the doc-editor reverted to what is
in SVN. These functions previously resolved to np.ma.core.get_data and
np.core.get_mask, but now resolve to np.core.getdata and
np.core.getmask. In retrospect, it's obvious that this will happen
when functions get renamed (even if the API and behaviour of Numpy
remain unchanged, as in this case), but not something that occurred to
me.

Any work done in the doc-editor can be recovered because the
doc-editors repository must contain the enhanced docstrings even
though they no longer appear on the web interface, but it is easy for
a similar situation to pass unnoticed in future. In this case it was
noticed and resolved, so no harm done.

This post is intended to draw developers attention to the possibility
of this occuring. Changes to docs in SVN are propogated once daily to
the doc-editor, but must be done manually in the opposite direction
for quality control. I'd suggest that a "best practice" when doing
similar refactoring should be to check for revised docstrings in the
doc-editor, do a quick or, preferably, thorough review and commit the
updated docstring to SVN before refactoring.

Cheers,
Scott