MAINT: Simplify return value of ndimage functions.

[jaimefrio]

Simplifies the return value of ndimage functions, so that the output array is always returned, instead of the awkward current behavior, where many (but not all) functions only return the output array if it has been allocated by the function, and return None if it has been passed by the user through the output= keyword argument.

[alan-isaac]

I am not making an objection but rather a offering a comment to document the apparent but so far unmentioned motivation for the original behavior: the idea that a function that mutates its argument should return None. It is therefore hard to consider such behavior unexpected or unintuitive; it might even be considered to be preferred. (E.g., https://mail.python.org/pipermail/python-dev/2003-October/038855.html )

[jaimefrio]

I understand and respect the distinction between .sort and sorted. And if we had two different functions, one taking an output and returning nothing, one not taking it and returning a new array, I could be convinced that's a reasonable state of things.

What I find harmful is having a single function that behaves wildly different depending on what its inputs are, because it basically forces you to have something like:

if output is None:
    return _nd_image_function(...)
else:
    _nd_image_function(...)
    return output

instead of the much more simple, readable and understandable:

return _nd_image_function(...)

[jaimefrio]

Aside from the change in return value behaviour, this also fixes a bug in the return value of binary_erosion with brute_force=True, iterations=0 and an output array was given: if the first iteration of the erosion returned the input unchanged, the result was never stored in output. Have added a test for that case.

[rgommers]

Needs a rebase. On merge also needs an entry in https://github.com/scipy/scipy/wiki/Release-note-entries-for-SciPy-1.1.0

[rgommers]

+1 for this change

[jaimefrio]

Have rebased. Once this is merged, will add the following text to the release notes in the Backwards incompatible changes section.

Functions in the ndimage module now always return their output array. Before this most functions only returned the output array if it had been allocated by the function, and would return None if it had been provided by the user.

[rgommers]

Okay in it goes. Thanks @jaimefrio!

[jaimefrio]

Thanks for the review!