#1727024: document that Popen.returncode is set by Popen.poll/wait.
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 17242c4..901ce4d 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -178,12 +178,14 @@
.. method:: Popen.poll()
- Check if child process has terminated. Returns returncode attribute.
+ Check if child process has terminated. Set and return :attr:`returncode`
+ attribute.
.. method:: Popen.wait()
- Wait for child process to terminate. Returns returncode attribute.
+ Wait for child process to terminate. Set and return :attr:`returncode`
+ attribute.
.. method:: Popen.communicate(input=None)
@@ -193,21 +195,21 @@
*input* argument should be a string to be sent to the child process, or
``None``, if no data should be sent to the child.
- communicate() returns a tuple (stdout, stderr).
+ :meth:`communicate` returns a tuple ``(stdout, stderr)``.
Note that if you want to send data to the process's stdin, you need to create
the Popen object with ``stdin=PIPE``. Similarly, to get anything other than
``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
``stderr=PIPE`` too.
-.. note::
+ .. note::
- The data read is buffered in memory, so do not use this method if the data size
- is large or unlimited.
+ The data read is buffered in memory, so do not use this method if the data
+ size is large or unlimited.
+
The following attributes are also available:
-
.. attribute:: Popen.stdin
If the *stdin* argument is ``PIPE``, this attribute is a file object that
@@ -233,9 +235,12 @@
.. attribute:: Popen.returncode
- The child return code. A ``None`` value indicates that the process hasn't
- terminated yet. A negative value -N indicates that the child was terminated by
- signal N (Unix only).
+ The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
+ by :meth:`communicate`). A ``None`` value indicates that the process
+ hasn't terminated yet.
+
+ A negative value ``-N`` indicates that the child was terminated by signal
+ ``N`` (Unix only).
Replacing Older Functions with the subprocess Module