[tor-commits] [stem/master] Revised API docs for stem.util.proc

[atagar at torproject.org]

commit cc37ede99703c0db0a34a3b3125339af473fe810
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Oct 27 15:35:37 2012 -0700

    Revised API docs for stem.util.proc
---
 docs/api.rst       |    1 +
 docs/contents.rst  |    1 +
 docs/util/proc.rst |    5 +++++
 stem/util/proc.py  |   37 ++++++++++++++++++++-----------------
 4 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 7a2392a..0078810 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -28,5 +28,6 @@ Utilities
 * `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities.
 * `stem.util.enum <util/enum.html>`_ - Enumeration class.
 * `stem.util.log <util/log.html>`_ - Logging utilities.
+* `stem.util.proc <util/proc.html>`_ - Tools to read a process' proc contents.
 * `stem.util.str_tools <util/str_tools.html>`_ - String utilities.
 
diff --git a/docs/contents.rst b/docs/contents.rst
index 3cc8928..5d900c1 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -24,5 +24,6 @@ Contents
    util/connection
    util/enum
    util/log
+   util/proc
    util/str_tools
 
diff --git a/docs/util/proc.rst b/docs/util/proc.rst
new file mode 100644
index 0000000..c5224a8
--- /dev/null
+++ b/docs/util/proc.rst
@@ -0,0 +1,5 @@
+Proc Utilities
+==============
+
+.. automodule:: stem.util.proc
+
diff --git a/stem/util/proc.py b/stem/util/proc.py
index a57e351..5315167 100644
--- a/stem/util/proc.py
+++ b/stem/util/proc.py
@@ -48,7 +48,7 @@ def is_available():
   """
   Checks if proc information is available on this platform.
   
-  :returns: bool that's True if proc contents exist on this platform, False otherwise
+  :returns: **True** if proc contents exist on this platform, **False** otherwise
   """
   
   global IS_PROC_AVAILABLE
@@ -74,9 +74,9 @@ def get_system_start_time():
   """
   Provides the unix time (seconds since epoch) when the system started.
   
-  :returns: float for the unix time of when the system started
+  :returns: **float** for the unix time of when the system started
   
-  :raises: IOError if it can't be determined
+  :raises: **IOError** if it can't be determined
   """
   
   global SYS_START_TIME
@@ -98,9 +98,9 @@ def get_physical_memory():
   """
   Provides the total physical memory on the system in bytes.
   
-  :returns: int for the bytes of physical memory this system has
+  :returns: **int** for the bytes of physical memory this system has
   
-  :raises: IOError if it can't be determined
+  :raises: **IOError** if it can't be determined
   """
   
   global SYS_PHYSICAL_MEMORY
@@ -124,9 +124,9 @@ def get_cwd(pid):
   
   :param int pid: process id of the process to be queried
   
-  :returns: str with the path of the workign direcctory for the process
+  :returns: **str** with the path of the workign direcctory for the process
   
-  :raises: IOError if it can't be determined
+  :raises: **IOError** if it can't be determined
   """
   
   start_time, parameter = time.time(), "cwd"
@@ -149,9 +149,9 @@ def get_uid(pid):
   
   :param int pid: process id of the process to be queried
   
-  :returns: int with the user id for the owner of the process
+  :returns: **int** with the user id for the owner of the process
   
-  :raises: IOError if it can't be determined
+  :raises: **IOError** if it can't be determined
   """
   
   start_time, parameter = time.time(), "uid"
@@ -173,9 +173,10 @@ def get_memory_usage(pid):
   
   :param int pid: process id of the process to be queried
   
-  :returns: tuple of two ints with the memory usage of the process, of the form ``(resident_size, virtual_size)``
+  :returns: **tuple** of two ints with the memory usage of the process, of the
+    form **(resident_size, virtual_size)**
   
-  :raises: IOError if it can't be determined
+  :raises: **IOError** if it can't be determined
   """
   
   # checks if this is the kernel process
@@ -208,9 +209,9 @@ def get_stats(pid, *stat_types):
   :param int pid: process id of the process to be queried
   :param Stat stat_types: information to be provided back
   
-  :returns: tuple with all of the requested statistics as strings
+  :returns: **tuple** with all of the requested statistics as strings
   
-  :raises: IOError if it can't be determined
+  :raises: **IOError** if it can't be determined
   """
   
   if CLOCK_TICKS is None:
@@ -268,9 +269,11 @@ def get_connections(pid):
   
   :param int pid: process id of the process to be queried
   
-  :returns: A listing of connection tuples of the form ``[(local_ipAddr1, local_port1, foreign_ipAddr1, foreign_port1), ...]`` (IP addresses are strings and ports are ints)
+  :returns: A listing of connection tuples of the form **[(local_ipAddr1,
+    local_port1, foreign_ipAddr1, foreign_port1), ...]** (IP addresses are
+    strings and ports are ints)
   
-  :raises: IOError if it can't be determined
+  :raises: **IOError** if it can't be determined
   """
   
   if pid == 0: return []
@@ -341,7 +344,7 @@ def _decode_proc_address_encoding(addr):
   
   :param str addr: proc address entry to be decoded
   
-  :returns: tuple of the form ``(addr, port)``, with addr as a string and port an int
+  :returns: **tuple** of the form **(addr, port)**, with addr as a string and port an int
   """
   
   ip, port = addr.split(':')
@@ -388,7 +391,7 @@ def _get_lines(file_path, line_prefixes, parameter):
   
   :returns: mapping of prefixes to the matching line
   
-  :raises: IOError if unable to read the file or can't find all of the prefixes
+  :raises: **IOError** if unable to read the file or can't find all of the prefixes
   """
   
   try: