Add documentation to our ping wrapper

spinn_utilities/ping.py

@@ -19,10 +19,26 @@
 
 
 class Ping(object):
+    """
+    Platform-independent ping support.
+    """
+
+    #: The unreachable host cache.
     unreachable = set()
 
     @staticmethod
     def ping(ipaddr):
+        """
+        Send a ping (ICMP ECHO request) to the given host.
+        SpiNNaker boards support ICMP ECHO when booted.
+
+        :param str ipaddr:
+            The IP address to ping. Hostnames can be used, but are not
+            recommended.
+        :return:
+            return code of subprocess; 0 for success, anything else for failure
+        :rtype: int
+        """
         if platform.platform().lower().startswith("windows"):
             cmd = "ping -n 1 -w 1 "
         else:
@@ -36,6 +52,14 @@ def ping(ipaddr):
 
     @staticmethod
     def host_is_reachable(ipaddr):
+        """
+        Test if a host is unreachable via ICMP ECHO. Note that this caches.
+
+        :param str ipaddr:
+            The IP address to ping. Hostnames can be used, but are not
+            recommended.
+        :rtype: bool
+        """
         if ipaddr in Ping.unreachable:
             return False
         tries = 0