[gnome-music/wip/mschraal/stylecleanup: 4/4] widgets: Docstrings for StarHandler & AlbumWidget

[Marinus Schraal <mschraal src gnome org>]

commit 8c4287ae452912a2113138b32a01839b92e1875c
Author: Marinus Schraal <mschraal src gnome org>
Date:   Sun May 22 22:21:29 2016 +0200

    widgets: Docstrings for StarHandler & AlbumWidget

 gnomemusic/widgets.py |   58 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 58 insertions(+), 0 deletions(-)
---
diff --git a/gnomemusic/widgets.py b/gnomemusic/widgets.py
index c06fec5..9a0f977 100644
--- a/gnomemusic/widgets.py
+++ b/gnomemusic/widgets.py
@@ -58,18 +58,32 @@ playlists = Playlists.get_default()
 
 
 class StarHandler():
+    """Handles the treeview column for favorites (stars)."""
 
     def __repr__(self):
         return '<StarHandler>'
 
     @log
     def __init__(self, parent, star_index):
+        """Initialize.
+
+        Keyword arguments:
+        parent -- the parent widget
+        star_index -- the column of the stars
+        """
         self.star_renderer_click = False
         self._star_index = star_index
         self._parent = parent
 
     @log
     def add_star_renderers(self, list_widget, cols, hidden=False):
+        """Adds the star renderer column
+
+        Keyword arguments:
+        list_widget -- the widget to add the favorites column
+        cols -- list of the widgets GtkTreeViewColumns
+        hidden -- visible state of the column
+        """
         star_renderer = CellRendererClickablePixbuf(self._parent.view,
                                                     hidden=hidden)
         star_renderer.connect("clicked", self._on_star_toggled)
@@ -80,6 +94,7 @@ class StarHandler():
 
     @log
     def _on_star_toggled(self, widget, path):
+        """Called if a star is clicked"""
         try:
             _iter = self._parent.model.get_iter(path)
         except TypeError:
@@ -112,6 +127,12 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def __init__(self, player, parent_view):
+        """Initialize the AlbumWidget.
+
+        Keyword arguments:
+        player -- the player object
+        parent_view -- the view this widget is part of
+        """
         Gtk.EventBox.__init__(self)
         self._player = player
         self._iter_to_clean = None
@@ -149,10 +170,12 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def _on_selection_mode_request(self, *args):
+        """Selection mode toggled."""
         self._header_bar._select_button.clicked()
 
     @log
     def _on_item_activated(self, widget, id, path):
+        """List row activated."""
         if self._star_handler.star_renderer_click:
             self._star_handler.star_renderer_click = False
             return
@@ -173,6 +196,7 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def _add_list_renderers(self):
+        """Create the ListView columns."""
         list_widget = self.view.get_generic_view()
 
         cols = list_widget.get_columns()
@@ -233,6 +257,7 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def _create_model(self):
+        """Create the ListStore model for this widget."""
         self.model = Gtk.ListStore(
             GObject.TYPE_STRING,  # title
             GObject.TYPE_STRING,
@@ -250,6 +275,15 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def update(self, artist, album, item, header_bar, selection_toolbar):
+        """Update the album widget.
+
+        Keyword arguments:
+        artist -- the artist name
+        album -- the album name
+        item -- the grilo media item
+        header_bar -- the header bar object
+        selection_toolbar -- the selection toolbar object
+        """
         self.selection_toolbar = selection_toolbar
         self._header_bar = header_bar
         self._album = album
@@ -293,12 +327,14 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def _on_header_cancel_button_clicked(self, button):
+        """Cancel selection mode callback."""
         self.view.set_selection_mode(False)
         self._header_bar.set_selection_mode(False)
         self._header_bar.header_bar.title = self._album
 
     @log
     def _on_header_select_button_toggled(self, button):
+        """Selection mode button clicked callback."""
         if button.get_active():
             self.view.set_selection_mode(True)
             self._header_bar.set_selection_mode(True)
@@ -317,6 +353,15 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def add_item(self, source, prefs, track, remaining, data=None):
+        """Add a song to the item to album list.
+
+        Keyword arguments:
+        source -- the grilo source
+        prefs --
+        track -- the grilo media object
+        remaining -- remaining number of items to add
+        data -- user data
+        """
         if track:
             self._duration = self._duration + track.get_duration()
             _iter = self.model.append()
@@ -331,6 +376,13 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def _on_look_up(self, pixbuf, path, data=None):
+        """Albumart retrieved callback.
+
+        Keyword arguments:
+        pixbuf -- the GtkPixbuf retrieved
+        path -- the filesystem location the pixbuf
+        data -- user data
+        """
         _iter = self._iter_to_clean
         if not pixbuf:
             pixbuf = self._no_artwork_icon
@@ -340,6 +392,12 @@ class AlbumWidget(Gtk.EventBox):
 
     @log
     def _update_model(self, player, playlist, currentIter):
+        """Player changed callback.
+
+        player -- the player object
+        playlist -- the current playlist
+        currentIter -- the current iter of the playlist model
+        """
         # self is not our playlist, return
         if (playlist != self.model):
             return False