Merge branch 'master' into 357-proc-cpu-num

1 files changed, 34 insertions, 22 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 360ef158..a18bba81 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -61,21 +61,29 @@ CPU
   Every attribute represents the seconds the CPU has spent in the given mode.
   The attributes availability varies depending on the platform:
 
-  - **user**
-  - **system**
-  - **idle**
+  - **user**: time spent by normal processes executing in user mode; on Linux
+    this also includes **guest** time
+  - **system**: time spent by processes executing in kernel mode
+  - **idle**: time spent doing nothing
 
   Platform-specific fields:
 
-  - **nice** *(UNIX)*
-  - **iowait** *(Linux)*
-  - **irq** *(Linux, BSD)*
-  - **softirq** *(Linux)*
-  - **steal** *(Linux 2.6.11+)*
-  - **guest** *(Linux 2.6.24+)*
-  - **guest_nice** *(Linux 3.2.0+)*
-  - **interrupt** *(Windows)*
-  - **dpc** *(Windows)*
+  - **nice** *(UNIX)*: time spent by niced processes executing in user mode;
+    on Linux this also includes **guest_nice** time
+  - **iowait** *(Linux)*: time spent waiting for I/O to complete
+  - **irq** *(Linux, BSD)*: time spent for servicing hardware interrupts
+  - **softirq** *(Linux)*: time spent for servicing software interrupts
+  - **steal** *(Linux 2.6.11+)*: time spent by other operating systems when
+    running in a virtualized environment
+  - **guest** *(Linux 2.6.24+)*: time spent running a virtual CPU for guest
+    operating systems under the control of the Linux kernel
+  - **guest_nice** *(Linux 3.2.0+)*: time spent running a niced guest
+    (virtual CPU for guest operating systems under the control of the Linux
+    kernel)
+  - **interrupt** *(Windows)*: time spent for servicing hardware interrupts (
+    similar to "irq" on UNIX)
+  - **dpc** *(Windows)*: time spent servicing deferred procedure calls (DPCs);
+    DPCs are interrupts that run at a lower priority than standard interrupts.
 
   When *percpu* is ``True`` return a list of namedtuples for each logical CPU
   on the system.
@@ -856,8 +864,8 @@ Process class
   .. method:: name()
 
     The process name.  On Windows the return value is cached after first
-    call. Not on POSIX because the process
-    `name may change <https://github.com/giampaolo/psutil/issues/692>`__.
+    call. Not on POSIX because the process name
+    `may change <https://github.com/giampaolo/psutil/issues/692>`__.
 
   .. method:: exe()
 
@@ -867,7 +875,8 @@ Process class
 
   .. method:: cmdline()
 
-    The command line this process has been called with.
+    The command line this process has been called with. The return value is not
+    cached because the cmdline of a process may change.
 
   .. method:: environ()
 
@@ -1135,7 +1144,7 @@ Process class
       multiple threads running on different CPU cores.
 
     .. note::
-      the returned value is explcitly **not** split evenly between all CPUs
+      the returned value is explicitly **not** split evenly between all CPUs
       cores (differently from :func:`psutil.cpu_percent()`).
       This means that a busy loop process running on a system with 2 CPU
       cores will be reported as having 100% CPU utilization instead of 50%.
@@ -1157,9 +1166,12 @@ Process class
     Get or set process current
     `CPU affinity <http://www.linuxjournal.com/article/6799?page=0,0>`__.
     CPU affinity consists in telling the OS to run a certain process on a
-    limited set of CPUs only. The number of eligible CPUs can be obtained with
-    ``list(range(psutil.cpu_count()))``. ``ValueError`` will be raise on set
-    in case an invalid CPU number is specified.
+    limited set of CPUs only.
+    On Linux this is done via the ``taskset`` command.
+    The number of eligible CPUs can be obtained with
+    ``list(range(psutil.cpu_count()))``.
+    ``ValueError`` will be raised on set in case an invalid CPU number is
+    specified.
 
       >>> import psutil
       >>> psutil.cpu_count()
@@ -1274,7 +1286,7 @@ Process class
       pmem(rss=15491072, vms=84025344, shared=5206016, text=2555904, lib=0, data=9891840, dirty=0)
 
     .. versionchanged::
-      4.0.0 mutiple fields are returned, not only `rss` and `vms`.
+      4.0.0 multiple fields are returned, not only `rss` and `vms`.
 
   .. method:: memory_info_ex()
 
@@ -1294,7 +1306,7 @@ Process class
     It does so by passing through the whole process address.
     As such it usually requires higher user privileges than
     :meth:`memory_info` and is considerably slower.
-    On platforms where extra fields are not implented this simply returns the
+    On platforms where extra fields are not implemented this simply returns the
     same metrics as :meth:`memory_info`.
 
     - **uss** *(Linux, OSX, Windows)*:
@@ -1864,7 +1876,7 @@ Constants
   Availability: Linux
 
   .. versionchanged::
-    3.0.0 on Python >= 3.4 thse constants are
+    3.0.0 on Python >= 3.4 these constants are
     `enums <https://docs.python.org/3/library/enum.html#module-enum>`__
     instead of a plain integer.