From ae17f987865ad57179408da4731e0c1935a354dd Mon Sep 17 00:00:00 2001
From: Giampaolo Rodola <g.rodola@gmail.com>
Date: Sun, 10 Apr 2016 19:29:29 +0200
Subject: [PATCH] update doc

---
 README.rst             | 23 +++++++++++++++++++++++
 docs/index.rst         | 15 ++++++++-------
 psutil/_pswindows.py   | 30 +++++++++++++++++++++++++++---
 scripts/winservices.py |  0
 4 files changed, 58 insertions(+), 10 deletions(-)
 mode change 100644 => 100755 scripts/winservices.py

diff --git a/README.rst b/README.rst
index 9fd92d79a..7bf8959d1 100644
--- a/README.rst
+++ b/README.rst
@@ -332,6 +332,29 @@ Further process APIs
     >>> gone, alive = psutil.wait_procs(procs_list, timeout=3, callback=on_terminate)
     >>>
 
+Windows services
+================
+
+.. code-block:: python
+
+    >>> list(psutil.win_service_iter())
+    [<WindowsService(name=AeLookupSvc, display_name=Application Experience) at 38850096>,
+     <WindowsService(name=ALG, display_name=Application Layer Gateway Service) at 38850128>,
+     <WindowsService(name=APNMCP, display_name=Ask Update Service) at 38850160>,
+     <WindowsService(name=AppIDSvc, display_name=Application Identity) at 38850192>,
+     ...
+    ]
+    >>> s = psutil.win_service_get('alg')
+    >>> s.as_dict()
+    {'binpath': 'C:\\Windows\\System32\\alg.exe',
+     'description': 'Provides support for 3rd party protocol plug-ins for Internet Connection Sharing',
+     'display_name': 'Application Layer Gateway Service',
+     'name': 'alg',
+     'pid': None,
+     'start_type': 'manual',
+     'status': 'stopped',
+     'username': 'NT AUTHORITY\\LocalService'}
+
 ======
 Donate
 ======
diff --git a/docs/index.rst b/docs/index.rst
index 2b2bf6ec5..7cff8d46f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1485,8 +1485,6 @@ Popen class
 Windows services
 ================
 
-.. note:: These APIs are Windows only.
-
 .. function:: win_service_iter()
 
   Return an iterator yielding a :class:`WindowsService` class instance for all
@@ -1511,16 +1509,18 @@ Windows services
 
   .. method:: name()
 
-     The service name. The value is cached on instantiation.
+     The service name. This string is how a service is referenced and can be
+     passed to :func:`win_service_get` to get a new :class:`WindowsService`
+     instance. The return value is cached on instantiation.
 
   .. method:: display_name()
 
-     The service display name. The value is cached on instantiation.
+     The service display name. The return value is cached on instantiation.
 
   .. method:: binpath()
 
-     The fully qualified path to the service binary/exe file including
-     arguments.
+     The fully qualified path to the service binary/exe file as a string,
+     including command line arguments.
 
   .. method:: username()
 
@@ -1532,7 +1532,8 @@ Windows services
 
   .. method:: pid()
 
-     The process PID, if any, else `None`.
+     The process PID, if any, else `None`. This can be passed to
+     :class:`Process` class to control the service's process.
 
   .. method:: status()
 
diff --git a/psutil/_pswindows.py b/psutil/_pswindows.py
index 61947deb1..d4c277843 100644
--- a/psutil/_pswindows.py
+++ b/psutil/_pswindows.py
@@ -9,7 +9,6 @@
 import functools
 import os
 import sys
-import time
 from collections import namedtuple
 
 from . import _common
@@ -342,6 +341,9 @@ def _query_status(self):
 
     @contextlib.contextmanager
     def _wrap_exceptions(self):
+        """Ctx manager which translates bare OSError and WindowsError
+        exceptions into NoSuchProcess and AccessDenied.
+        """
         try:
             yield
         except WindowsError as err:
@@ -361,34 +363,57 @@ def _wrap_exceptions(self):
     # config query
 
     def name(self):
+        """The service name. This string is how a service is referenced
+        and can be passed to win_service_get() to get a new
+        WindowsService instance. The return value is cached on
+        instantiation.
+        """
         return self._name
 
     def display_name(self):
+        """The service display name. The return value is cached on
+        instantiation.
+        """
         return self._display_name
 
     def binpath(self):
+        """The fully qualified path to the service binary/exe file as
+        a string, including command line arguments.
+        """
         return self._query_config()['binpath']
 
     def username(self):
+        """The name of the user that owns the service."""
         return self._query_config()['username']
 
     def start_type(self):
+        """A string which can either be "automatic", "manual" or
+        "disabled".
+        """
         return self._query_config()['start_type']
 
     # status query
 
     def pid(self):
+        """The process PID, if any, else `None`. This can be passed
+        to Process class to control the service's process.
+        """
         return self._query_status()['pid']
 
     def status(self):
+        """Service status as a string."""
         return self._query_status()['status']
 
     def description(self):
+        """Service long description."""
         return cext.winservice_query_descr(self.name())
 
     # utils
 
     def as_dict(self):
+        """Utility method retrieving all the information above as a
+        dictionary.
+        """
         d = self._query_config()
         d.update(self._query_status())
         d['name'] = self.name()
@@ -445,8 +470,7 @@ def win_service_iter():
 def win_service_get(name):
     """Open a Windows service and return it as a WindowsService instance."""
     service = WindowsService(name, None)
-    display_name, _, _, _ = service._query_config()
-    service._display_name = display_name
+    service._display_name = service._query_config()['display_name']
     return service
 
 
diff --git a/scripts/winservices.py b/scripts/winservices.py
old mode 100644
new mode 100755