Updades description of the popen module

doc/reference/reference_lua/popen.rst

@@ -30,13 +30,6 @@ object:
   syscall
 * :ref:`popen.new <popen-new>` to create a popen object with more specific options
 
-Either function returns a handle which we will call ``popen_handle`` or ``ph``.
-With the handle one can execute methods.
-
-===============================================================================
-                                    Index
-===============================================================================
-
 Below is a list of all ``popen`` functions and handle methods.
 
 ..  container:: table
@@ -87,6 +80,10 @@ Below is a list of all ``popen`` functions and handle methods.
     | <popen-handle_fields>`               |                                 |
     +--------------------------------------+---------------------------------+
 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+                      popen module constructors
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
 ..  _popen-shell:
 
 ..  function:: shell(command [, mode])
@@ -95,8 +92,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
     :param string command: a command to run, mandatory
     :param string mode: communication mode, optional
-    :return: (if success) a popen handle, which we will call
-             ``popen_handle`` or ``ph``
+    :return: (if success) a popen handle object
 
              (if failure) ``nil, err``
 
@@ -160,8 +156,7 @@ Below is a list of all ``popen`` functions and handle methods.
                        mandatory; absolute path to the program is required when
                        ``opts.shell`` is false (default)
     :param table opts: table of options, optional
-    :return: (if success) a popen handle, which we will call
-             ``popen_handle`` or ``ph``
+    :return: (if success) a popen handle object
 
              (if failure) ``nil, err``
 
@@ -251,7 +246,7 @@ Below is a list of all ``popen`` functions and handle methods.
         |                      |                | or when Lua GC collects the handle.       |
         +----------------------+----------------+-------------------------------------------+
 
-    The returned ``ph`` handle provides a
+    The returned ``popen_handle`` handle provides a
     :ref:`popen_handle:close() <popen-close>` method for explicitly
     releasing all occupied resources, including the child process
     itself if ``opts.keep_child`` is not set). However, if the ``close()``
@@ -394,7 +389,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Read data from a child peer.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :param table opts: options
@@ -437,7 +432,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Write string ``str`` to stdin stream of a child process.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :param string str: string to write
@@ -480,7 +475,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Close parent's ends of std* fds.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :param table opts: options
@@ -535,7 +530,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Send SIGTERM signal to a child process.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :return: see :ref:`popen_handle:signal() <popen-signal>` for errors and
@@ -551,7 +546,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Send SIGKILL signal to a child process.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :return: see :ref:`popen_handle:signal() <popen-signal>` for errors and
@@ -568,7 +563,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Send signal to a child process.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :param number signo: signal to send
@@ -611,7 +606,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Return information about the popen handle.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :return: (if success) formatted result
@@ -743,7 +738,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Wait until a child process gets exited or signaled.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :param number timeout: since version :doc:`3.2.0 </release/3.2.0>`. The parameter defines the period in seconds for the method to wait for a resolution. The default value is "infinity".
@@ -785,7 +780,7 @@ Below is a list of all ``popen`` functions and handle methods.
 
         Close a popen handle.
 
-        :param handle ph: handle of a child process created with
+        :param userdata ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
         :return: (if success) true
@@ -835,6 +830,10 @@ Below is a list of all ``popen`` functions and handle methods.
         means success for a caller. The return values are purely
         informational: they are for logging or some kind of reporting.
 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+                      popen handle fields
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
     ..  _popen-handle_fields:
 
     **Handle fields**
@@ -851,6 +850,10 @@ Below is a list of all ``popen`` functions and handle methods.
 
     See :ref:`popen_handle:info() <popen-info>` for details.
 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+                      popen module constants
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
     ..  _popen-constants:
 
     **Module constants**