# HG changeset patch
# Parent 3deec794cfcf6ac403579f325073e375295ef374
# Parent  a92466bf16ccb460f1a054ce9c0ef426a8ab6b37
Issue #22413: Document newline effect on StringIO initializer and getvalue

Also add to comment in the C code and remove another comment made out of date
by Argument Clinic.

diff -r a92466bf16cc Doc/library/io.rst
--- a/Doc/library/io.rst	Sat Oct 03 07:54:08 2015 +0000
+++ b/Doc/library/io.rst	Sat Oct 03 09:30:15 2015 +0000
@@ -889,10 +889,16 @@
    An in-memory stream for text I/O.  The text buffer is discarded when the
    :meth:`~IOBase.close` method is called.
 
-   The initial value of the buffer (an empty string by default) can be set by
-   providing *initial_value*.  The *newline* argument works like that of
-   :class:`TextIOWrapper`.  The default is to consider only ``\n`` characters
-   as end of lines and to do no newline translation.
+   The initial value of the buffer can be set by providing *initial_value*.
+   If newline translation is enabled, newlines will be encoded as if by
+   :meth:`~TextIOBase.write`.  The stream is positioned at the start of
+   the buffer.
+
+   The *newline* argument works like that of :class:`TextIOWrapper`.
+   The default is to consider only ``\n`` characters as ends of lines and
+   to do no newline translation.  If *newline* is set to ``None``,
+   newlines are written as ``\n`` on all platforms, but universal
+   newline decoding is still performed when reading.
 
    :class:`StringIO` provides this method in addition to those from
    :class:`TextIOBase` and its parents:
@@ -900,6 +906,8 @@
    .. method:: getvalue()
 
       Return a ``str`` containing the entire contents of the buffer.
+      Newlines are decoded as if by :meth:`~TextIOBase.read`, although
+      the stream position is not changed.
 
    Example usage::
 
diff -r a92466bf16cc Modules/_io/_iomodule.h
--- a/Modules/_io/_iomodule.h	Sat Oct 03 07:54:08 2015 +0000
+++ b/Modules/_io/_iomodule.h	Sat Oct 03 09:30:15 2015 +0000
@@ -52,7 +52,12 @@
    which can be safely put aside until another search.
 
    NOTE: for performance reasons, `end` must point to a NUL character ('\0').
-   Otherwise, the function will scan further and return garbage. */
+   Otherwise, the function will scan further and return garbage.
+
+   There are three modes, in order of priority:
+   * translated: Only find \n (assume newlines already translated)
+   * universal: Use universal newlines algorithm
+   * Otherwise, the line ending is specified by readnl, a str object */
 extern Py_ssize_t _PyIO_find_line_ending(
     int translated, int universal, PyObject *readnl,
     int kind, char *start, char *end, Py_ssize_t *consumed);
diff -r a92466bf16cc Modules/_io/stringio.c
--- a/Modules/_io/stringio.c	Sat Oct 03 07:54:08 2015 +0000
+++ b/Modules/_io/stringio.c	Sat Oct 03 09:30:15 2015 +0000
@@ -696,10 +696,6 @@
     char *newline = "\n";
     Py_ssize_t value_len;
 
-    /* Parse the newline argument. This used to be done with the 'z'
-       specifier, however this allowed any object with the buffer interface to
-       be converted. Thus we have to parse it manually since we only want to
-       allow unicode objects or None. */
     if (newline_obj == Py_None) {
         newline = NULL;
     }