redshift-gtk: Add docstrings in statusicon module

src/redshift-gtk/statusicon.py

@@ -45,7 +45,13 @@ def sigterm_handler(signal, frame):
 
 
 class RedshiftStatusIcon(object):
+    '''A status icon and a wrapper around a redshift child process'''
+
     def __init__(self, args=[]):
+        '''Creates a new instance of the status icon and runs the child process
+
+        The args is a list of arguments to pass to the child process.'''
+
         # Initialize state variables
         self._status = False
         self._temperature = 0
@@ -195,6 +201,10 @@ class RedshiftStatusIcon(object):
         Gdk.notify_startup_complete()
 
     def start_child_process(self, args):
+        '''Start the child process
+
+        The args is a list of command list arguments to pass to the child process.'''
+
         # Start child process with C locale so we can parse the output
         env = os.environ.copy()
         env['LANG'] = env['LANGUAGE'] = env['LC_ALL'] = env['LC_MESSAGES'] = 'C'
@@ -203,11 +213,18 @@ class RedshiftStatusIcon(object):
                                         standard_output=True, standard_error=True)
 
     def remove_suspend_timer(self):
+        '''Disable any previously set suspend timer'''
         if self.suspend_timer is not None:
             GLib.source_remove(self.suspend_timer)
             self.suspend_timer = None
 
     def suspend_cb(self, item, minutes):
+        '''Callback that handles activation of a suspend timer
+
+        The minutes parameter is the number of minutes to suspend. Even if redshift
+        is not disabled when called, it will still set a suspend timer and
+        reactive redshift when the timer is up.'''
+
         if self.is_enabled():
             self.child_toggle_status()
 
@@ -219,19 +236,26 @@ class RedshiftStatusIcon(object):
         self.suspend_timer = GLib.timeout_add_seconds(minutes * 60, self.reenable_cb)
 
     def reenable_cb(self):
+        '''Callback to reenable redshift when a suspend timer expires'''
         if not self.is_enabled():
             self.child_toggle_status()
 
     def popup_menu_cb(self, widget, button, time, data=None):
+        '''Callback when the popup menu on the status icon has to open'''
         self.status_menu.show_all()
         self.status_menu.popup(None, None, Gtk.StatusIcon.position_menu,
                                self.status_icon, button, time)
 
     def toggle_cb(self, widget, data=None):
+        '''Callback when a request to toggle redshift was made'''
         self.remove_suspend_timer()
         self.child_toggle_status()
 
     def toggle_item_cb(self, widget, data=None):
+        '''Callback then a request to toggle redshift was made from a toggle item
+
+        This ensures that the state of redshift is synchronised with
+        the toggle state of the widget (e.g. Gtk.CheckMenuItem).'''
         # Only toggle if a change from current state was requested
         if self.is_enabled() != widget.get_active():
             self.remove_suspend_timer()
@@ -239,12 +263,19 @@ class RedshiftStatusIcon(object):
 
     # Info dialog callbacks
     def show_info_cb(self, widget, data=None):
+        '''Callback when the info dialog should be presented'''
         self.info_dialog.show()
 
     def response_info_cb(self, widget, data=None):
+        '''Callback when a button in the info dialog was activated'''
         self.info_dialog.hide()
 
     def update_status_icon(self):
+        '''Update the status icon according to the internally recorded state
+
+        This should be called whenever the internally recorded state
+        might have changed.'''
+
         # Update status icon
         if appindicator:
             if self.is_enabled():
@@ -257,9 +288,8 @@ class RedshiftStatusIcon(object):
             else:
                 self.status_icon.set_from_icon_name('redshift-status-off')
 
-    # Status update functions. Called when child process indicates a
-    # change in state.
     def change_status(self, status):
+        '''Change internally recorded state of redshift'''
         self._status = status
 
         self.update_status_icon()
@@ -268,34 +298,43 @@ class RedshiftStatusIcon(object):
                                                             _('Enabled') if status else _('Disabled')))
 
     def change_temperature(self, temperature):
+        '''Change internally recorded temperature of redshift'''
         self._temperature = temperature
         self.temperature_label.set_markup('<b>{}:</b> {}K'.format(_('Color temperature'), temperature))
 
     def change_period(self, period):
+        '''Change internally recorded period of redshift'''
         self._period = period
         self.period_label.set_markup('<b>{}:</b> {}'.format(_('Period'), period))
 
     def change_location(self, location):
+        '''Change internally recorded location of redshift'''
         self._location = location
         self.location_label.set_markup('<b>{}:</b> {}, {}'.format(_('Location'), *location))
 
 
     def is_enabled(self):
+        '''Return the internally recorded state of redshift'''
         return self._status
 
     def autostart_cb(self, widget, data=None):
+        '''Callback when a request to toggle autostart is made'''
         utils.set_autostart(widget.get_active())
 
     def destroy_cb(self, widget, data=None):
+        '''Callback when a request to quit the application is made'''
         if not appindicator:
             self.status_icon.set_visible(False)
         Gtk.main_quit()
         return False
 
     def child_toggle_status(self):
+        '''Sends a request to the child process to toggle state'''
         os.kill(self.process[0], signal.SIGUSR1)
 
     def child_cb(self, pid, status, data=None):
+        '''Called when the child process exists'''
+
         # Empty stdout and stderr
         for f, dest in ((self.process[2], sys.stdout),
                          (self.process[3], sys.stderr)):
@@ -322,6 +361,7 @@ class RedshiftStatusIcon(object):
             sys.exit(-1)
 
     def child_key_change_cb(self, key, value):
+        '''Called when the child process reports a change of internal state'''
         if key == 'Status':
             self.change_status(value != 'Disabled')
         elif key == 'Color temperature':
@@ -332,6 +372,7 @@ class RedshiftStatusIcon(object):
             self.change_location(value.split(', '))
 
     def child_stdout_line_cb(self, line):
+        '''Called when the child process outputs a line to stdout'''
         if line:
             m = re.match(r'([\w ]+): (.+)', line)
             if m:
@@ -340,6 +381,8 @@ class RedshiftStatusIcon(object):
                 self.child_key_change_cb(key, value)
 
     def child_data_cb(self, f, cond, data):
+        '''Called when the child process has new data on stdout/stderr'''
+
         stdout, ib = data
         ib.buf += os.read(f, 256).decode('utf-8')
 
@@ -357,6 +400,7 @@ class RedshiftStatusIcon(object):
         return True
 
     def termwait(self):
+        '''Send SIGINT and wait for the child process to quit'''
         try:
             os.kill(self.process[0], signal.SIGINT)
             os.waitpid(self.process[0], 0)