ENH: add nditer.close as per review

2 files changed, 13 insertions, 11 deletions

diff --git a/doc/release/1.15.0-notes.rst b/doc/release/1.15.0-notes.rst
index 963f72209..1bd0673b5 100644
--- a/doc/release/1.15.0-notes.rst
+++ b/doc/release/1.15.0-notes.rst
@@ -52,10 +52,6 @@ Deprecations
   In the future, it might return a different result. Use `np.sum(np.from_iter(generator))`
   or the built-in Python `sum` instead.
 
-* ``nditer`` use outside of a context manager where the ``nditer`` has writable
-  arrays is deprecated. This situation proves difficult to detect, the
-  ``DeprecationWarning`` may only be emitted when deallocating the array.
-
 * Users of the C-API should call ``PyArrayResolveWriteBackIfCopy`` or 
   ``PyArray_DiscardWritbackIfCopy`` on any array with the ``WRITEBACKIFCOPY``
   flag set, before the array is deallocated. A deprecation warning will be
@@ -63,9 +59,9 @@ Deprecations
 
 * Users of ``nditer`` should use the nditer object as a context manager
   anytime one of the iterator operands is writeable, so that numpy can
-  manage writeback semantics. A deprecation warning will be emitted if a
-  context manager is not used in these cases. Users of the C-API should call 
-  ``NpyIter_Close`` before ``NpyIter_Dealloc``.
+  manage writeback semantics, or should call ``it.close()``. A
+ `RuntimeWarning` will be emitted otherwise in these cases. Users of the C-API
+  should call ``NpyIter_Close`` before ``NpyIter_Dealloc``.
 
 
 Future Changes
@@ -84,7 +80,10 @@ copy, nditer later writes those changes back into your actual array. Currently,
 this writeback occurs when the array objects are garbage collected, which makes
 this API error-prone on CPython and entirely broken on PyPy. Therefore, 
 ``nditer`` should now be used as a context manager whenever using ``nditer``
-with writeable arrays (``with np.nditer(...) as it: ...``). 
+with writeable arrays (``with np.nditer(...) as it: ...``). You may also
+explicitly call ``it.close()`` for cases where a context manager is unusable,
+for instance in generator expressions.
+
 Numpy has switched to using pytest instead of nose for testing
 --------------------------------------------------------------
 The last nose release was 1.3.7 in June, 2015, and development of that tool has
diff --git a/doc/source/reference/arrays.nditer.rst b/doc/source/reference/arrays.nditer.rst
index 710ad8be6..911ff6671 100644
--- a/doc/source/reference/arrays.nditer.rst
+++ b/doc/source/reference/arrays.nditer.rst
@@ -85,9 +85,12 @@ By default, the :class:`nditer` treats the input array as a read-only
 object. To modify the array elements, you must specify either read-write
 or write-only mode. This is controlled with per-operand flags. The
 operands may be created as views into the original data with the 
-`WRITEBACKIFCOPY` flag. In this case the iterator must be used as a context
-manager, and the temporary data will be written back to the original array
-when the `__exit__` function is called.
+`WRITEBACKIFCOPY` flag. In this case the iterator must either
+
+- be used as a context manager, and the temporary data will be written back
+  to the original array when the `__exit__` function is called.
+- have a call to the iterator's `close` function to ensure the modified data
+  is written back to the original array.
 
 Regular assignment in Python simply changes a reference in the local or
 global variable dictionary instead of modifying an existing variable in