[core/module] Add docstrings

bumblebee_status/core/module.py

@@ -15,6 +15,17 @@ except Exception as e:
 log = logging.getLogger(__name__)
 
 
+"""Loads a module by name
+
+:param module_name: Name of the module to load
+:param config: Configuration to apply to the module (defaults to an empty configuration)
+:param theme: Theme for this module, defaults to None, which means whatever is configured in "config"
+
+:return: A module object representing the module, or an Error module if loading failed
+:rtype: class bumblebee_status.module.Module
+"""
+
+
 def load(module_name, config=core.config.Config([]), theme=None):
     error = None
     module_short, alias = (module_name.split(":") + [module_name])[0:2]
@@ -36,6 +47,13 @@ def load(module_name, config=core.config.Config([]), theme=None):
 
 
 class Module(core.input.Object):
+    """Represents a module (single piece of functionality) of the bar
+
+    :param config: Configuration to apply to the module (defaults to an empty configuration)
+    :param theme: Theme for this module, defaults to None, which means whatever is configured in "config"
+    :param widgets: A list of bumblebee_status.widget.Widget objects that the module is comprised of
+    """
+
     def __init__(self, config=core.config.Config([]), theme=None, widgets=[]):
         super().__init__()
         self.__config = config
@@ -52,23 +70,55 @@ class Module(core.input.Object):
         for widget in self.__widgets:
             widget.module = self
 
+    """Override this to determine when to show this module
+
+    :return: True if the module should be hidden, False otherwise
+    :rtype: boolean
+    """
+
     def hidden(self):
         return False
 
+    """Retrieve CLI/configuration parameters for this module. For example, if
+    the module is called "test" and the user specifies "-p test.x=123" on the
+    commandline, using self.parameter("x") retrieves the value 123.
+
+    :param key: Name of the parameter to retrieve
+    :param default: Default value, if parameter is not set by user (defaults to None)
+
+    :return: Parameter value, or default
+    :rtype: string
+    """
+
     def parameter(self, key, default=None):
         value = default
 
         for prefix in [self.name, self.module_name, self.alias]:
             value = self.__config.get("{}.{}".format(prefix, key), value)
-        # TODO retrieve from config file
         return value
 
+    """Set a parameter for this module
+
+    :param key: Name of the parameter to set
+    :param value: New value of the parameter
+    """
+
     def set(self, key, value):
         self.__config.set("{}.{}".format(self.name, key), value)
 
+    """Override this method to define tasks that should be done during each
+    update interval (for instance, querying an API, calling a CLI tool to get new
+    date, etc.
+    """
+
     def update(self):
         pass
 
+    """Wrapper method that ensures that all exceptions thrown by the
+    update() method are caught and displayed in a bumblebee_status.module.Error
+    module
+    """
+
     def update_wrapper(self):
         try:
             self.update()
@@ -78,17 +128,42 @@ class Module(core.input.Object):
             self.__widgets = [module.widget()]
             self.update = module.update
 
+    """Retrieves the list of widgets for this module
+
+    :return: A list of widgets
+    :rtype: list of bumblebee_status.widget.Widgets
+    """
+
     def widgets(self):
         return self.__widgets
 
+    """Removes all widgets of this module"""
+
     def clear_widgets(self):
         del self.__widgets[:]
 
+    """Adds a widget to the module
+
+    :param full_text: Text or callable (method) that defines the text of the widget (defaults to "")
+    :param name: Name of the widget, defaults to None, which means autogenerate
+
+    :return: The new widget
+    :rtype: bumblebee_status.widget.Widget
+    """
+
     def add_widget(self, full_text="", name=None):
         widget = core.widget.Widget(full_text=full_text, name=name, module=self)
         self.widgets().append(widget)
         return widget
 
+    """Convenience method to retrieve a named widget
+
+    :param name: Name of widget to retrieve, defaults to None (in which case the first widget is returned)
+
+    :return: The widget with the corresponding name, None if not found
+    :rtype: bumblebee_status.widget.Widget
+    """
+
     def widget(self, name=None):
         if not name:
             return self.widgets()[0]
@@ -98,9 +173,27 @@ class Module(core.input.Object):
                 return w
         return None
 
+    """Override this method to define states for the module
+
+    :param widget: Widget for which state should be returned
+
+    :return: a list of states for this widget
+    :rtype: list of strings
+    """
+
     def state(self, widget):
         return []
 
+    """Convenience method that sets warning and critical state for numbers
+
+    :param value: Current value to calculate state against
+    :param warn: Warning threshold
+    :parm crit: Critical threshold
+
+    :return: None if value is below both thresholds, "critical", "warning" as appropriate otherwise
+    :rtype: string
+    """
+
     def threshold_state(self, value, warn, crit):
         if value > float(self.parameter("critical", crit)):
             return "critical"
@@ -110,14 +203,28 @@ class Module(core.input.Object):
 
 
 class Error(Module):
+    """Represents an "error" module
+
+    :param module: The module name that produced the error
+    :param error: The error message to display
+    :param config: Configuration to apply to the module (defaults to an empty configuration)
+    :param theme: Theme for this module, defaults to None, which means whatever is configured in "config"
+    """
+
     def __init__(self, module, error, config=core.config.Config([]), theme=None):
         super().__init__(config, theme, core.widget.Widget(self.full_text))
         self.__module = module
         self.__error = error
 
+    """Returns the error message
+    :param widget: the error widget to display
+    """
+
     def full_text(self, widget):
         return "{}: {}".format(self.__module, self.__error)
 
+    """Overriden state, always returns critical (it *is* an error, after all"""
+
     def state(self, widget):
         return ["critical"]