docs: Document the helper functions

Create the in-code documentation for helper functions for automodule
documentation.

Signed-off-by: Fabien Lahoudere <fabien.lahoudere@collabora.com>
Signed-off-by: Enric Balletbo i Serra <enric.balletbo@collabora.com>

3 files changed, 23 insertions, 2 deletions

diff --git a/cros/helpers/kernel.py b/cros/helpers/kernel.py
index d36bb87..db0c69f 100644
--- a/cros/helpers/kernel.py
+++ b/cros/helpers/kernel.py
@@ -2,14 +2,18 @@
 # -*- coding: utf-8 -*-
 
 
-# Return an int froom kernel version to allow to compare
 def version_to_int(version, major, minor):
+    """ Return an integer from kernel version to allow to compare with
+        others.
+    """
     pattern = "{0:03d}{1:03d}{2:03d}"
     return int(pattern.format(version, major, minor))
 
 
-# Return the running kernel version
 def current_kernel_version():
+    """ Returns the current kernel version as an integer you can
+        compare.
+    """
     fd = open("/proc/version", "r")
     current = fd.read().split()[2].split("-")[0].split(".")
     fd.close()
@@ -17,12 +21,18 @@ def current_kernel_version():
 
 
 def kernel_lower_than(version, major, minor):
+    """ Returns true if the given version is lower than the running kernel
+        version.
+    """
     if version_to_int(version, major, minor) > current_kernel_version():
         return True
     return False
 
 
 def kernel_greater_than(version, major, minor):
+    """ Returns true if the given version is greater than the running kernel
+        version.
+    """
     if version_to_int(version, major, minor) < current_kernel_version():
         return True
     return False
diff --git a/cros/helpers/mcu.py b/cros/helpers/mcu.py
index 1855788..2fc6e96 100644
--- a/cros/helpers/mcu.py
+++ b/cros/helpers/mcu.py
@@ -95,6 +95,9 @@ def EC_FEATURE_MASK_1(event_code):
 
 
 def is_feature_supported(feature):
+    """ Returns true if the Embedded Controller supports the specified
+        'feature'.
+    """
     global ECFEATURES
 
     if ECFEATURES == -1:
@@ -124,6 +127,9 @@ def is_feature_supported(feature):
 
 
 def check_mcu_abi(s, name):
+    """ Checks that the MCU character device exists in /dev and then verifies
+        the standard MCU ABI in /sys/class/chromeos.
+    """
     if not os.path.exists("/dev/cros_" + name):
         s.skipTest("MCU " + name + " not supported, skipping")
     files = ["flashinfo", "reboot", "version"]
diff --git a/cros/helpers/sysfs.py b/cros/helpers/sysfs.py
index 0700c01..8e52491 100644
--- a/cros/helpers/sysfs.py
+++ b/cros/helpers/sysfs.py
@@ -5,6 +5,7 @@ import os
 
 
 def read_file(name):
+    """ Returns the content of the file named 'name'."""
     fd = open(name, "r")
     contents = fd.read()
     fd.close()
@@ -12,6 +13,10 @@ def read_file(name):
 
 
 def sysfs_check_attributes_exists(s, path, name, files, check_devtype):
+    """ Checks that all attributes listed in 'files' for a given 'path' exists.
+        Note that the 'name' parameter is used to define a pattern to match
+        before checking a device path.
+    """
     match = 0
     for devname in os.listdir(path):
         if check_devtype: