doc: docstrings for new stuff in alot.settings.*

2 files changed, 43 insertions, 13 deletions

diff --git a/alot/settings/__init__.py b/alot/settings/__init__.py
index dacdcc9f..9f533936 100644
--- a/alot/settings/__init__.py
+++ b/alot/settings/__init__.py
@@ -225,13 +225,16 @@ class SettingsManager(object):
         :type mode: str
         :param name: identifier of the atttribute
         :type name: str
+        :rtype: urwid.AttrSpec
         """
         colours = int(self._config.get('colourmode'))
         return self._theme.get_attribute(mode, name,  colours)
 
     def get_threadline_theming(self, thread):
         """
-        looks up theming info a threadline displaying a given thread
+        looks up theming info a threadline displaying a given thread. This
+        wraps around :meth:`~alot.settings.theme.Theme.get_threadline_theming`,
+        filling in the current colour mode.
 
         :param thread: thread to theme
         :type thread: alot.db.thread.Thread
@@ -242,20 +245,23 @@ class SettingsManager(object):
     def get_tagstring_representation(self, tag, onebelow_normal=None,
                                      onebelow_focus=None):
         """
-        looks up user's preferred way to represent a given tagstring
-        on top of a widget with given attributes that shine though
-        for '' and 'default' values.
-
-        This returns a dictionary mapping 'normal' and 'focussed' to
-        `urwid.AttrSpec` attributes, 'translated' to an alternative string
-        representation and 'hidden' to a boolean flag.
+        looks up user's preferred way to represent a given tagstring.
 
         :param tag: tagstring
         :type tag: str
-        :param onebelow_normal: attribute that shine through if unfocussed
+        :param onebelow_normal: attribute that shines through if unfocussed
         :type onebelow_normal: urwid.AttrSpec
         :param onebelow_focus: attribute that shines through if focussed
-        :type onebelow_focus : urwid.AttrSpec
+        :type onebelow_focus: urwid.AttrSpec
+
+        If `onebelow_normal` or `onebelow_focus` is given these attributes will
+        be used as fallbacks for fg/bg values '' and 'default'.
+
+        This returns a dictionary mapping
+            :normal: to :class:`urwid.AttrSpec` used if unfocussed
+            :focussed: to :class:`urwid.AttrSpec` used if focussed
+            :translated: to an alternative string representation
+            :hidden: to a boolean
         """
         colourmode = int(self._config.get('colourmode'))
         theme = self._theme
diff --git a/alot/settings/theme.py b/alot/settings/theme.py
index 563296c5..d225e646 100644
--- a/alot/settings/theme.py
+++ b/alot/settings/theme.py
@@ -43,9 +43,6 @@ class Theme(object):
                         msg = 'missing threadline parts: %s' % difference
                         raise ConfigError(msg)
 
-    def _by_colour(self, triple, colour):
-        return triple[self._colours.index(colour)]
-
     def get_attribute(self, mode, name, colourmode):
         """
         returns requested attribute
@@ -56,10 +53,37 @@ class Theme(object):
         :type name: str
         :param colourmode: colour mode; in [1, 16, 256]
         :type colourmode: int
+        :rtype: urwid.AttrSpec
         """
         return self._config[mode][name][self._colours.index(colourmode)]
 
     def get_threadline_theming(self, thread, colourmode):
+        """
+        look up how to display a Threadline wiidget in search mode
+        for a given thread.
+
+        :param thread: Thread to theme Threadline for
+        :type thread: alot.db.thread.Thread
+        :param colourmode: colourmode to use, one of 1,16,256.
+        :type colourmode: int
+
+        This will return a dict mapping
+            :normal: to `urwid.AttrSpec`,
+            :focus: to `urwid.AttrSpec`,
+            :parts: to a list of strings indentifying subwidgets
+                    to be displayed in this order.
+
+        Moreover, for every part listed this will map 'part' to a dict mapping
+            :normal: to `urwid.AttrSpec`,
+            :focus: to `urwid.AttrSpec`,
+            :width: to a tuple indicating the width of the subpart.
+                    This is either `('fit', min, max)` to force the widget
+                    to be at least `min` and at most `max` characters wide,
+                    or `('weight', n)` which makes it share remaining space
+                    with other 'weight' parts.
+            :alignment: where to place the content if shorter than the widget.
+                        This is either 'right', 'left' or 'center'.
+        """
         def pickcolour(triple):
             return triple[self._colours.index(colourmode)]