More docstrings

openlp/core/lib/serviceitem.py

@@ -22,6 +22,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`serviceitem` provides the service item functionality including the
+type and capability of an item.
+"""
 
 import logging
 import os
@@ -43,6 +47,9 @@ class ServiceItemType(object):
     Command = 3
 
 class ItemCapabilities(object):
+    """
+    Provides an enumeration of a serviceitem's capabilities
+    """
     AllowsPreview = 1
     AllowsEdit = 2
     AllowsMaintain = 3
@@ -85,9 +92,21 @@ class ServiceItem(object):
         self.cache = []
 
     def add_capability(self, capability):
+        """
+        Add an ItemCapability to a ServiceItem
+
+        ``capability``
+            The capability to add
+        """
         self.capabilities.append(capability)
 
     def is_capable(self, capability):
+        """
+        Tell the caller if a ServiceItem has a capability
+
+        ``capability``
+            The capability to test for
+        """
         return capability in self.capabilities
 
     def addIcon(self, icon):
@@ -304,22 +323,40 @@ class ServiceItem(object):
         return self._uuid != other._uuid
 
     def is_media(self):
+        """
+        Confirms if the ServiceItem is media
+        """
         return ItemCapabilities.RequiresMedia in self.capabilities
 
     def is_command(self):
+        """
+        Confirms if the ServiceItem is a command
+        """
         return self.service_item_type == ServiceItemType.Command
 
     def is_image(self):
+        """
+        Confirms if the ServiceItem is an image
+        """
         return self.service_item_type == ServiceItemType.Image
 
     def uses_file(self):
+        """
+        Confirms if the ServiceItem uses a file
+        """
         return self.service_item_type == ServiceItemType.Image or \
             self.service_item_type == ServiceItemType.Command
 
     def is_text(self):
+        """
+        Confirms if the ServiceItem is text
+        """
         return self.service_item_type == ServiceItemType.Text
 
     def get_frames(self):
+        """
+        Returns the frames for the ServiceItem
+        """
         if self.service_item_type == ServiceItemType.Text:
             return self._display_frames
         else:

openlp/core/lib/songxmlhandler.py

@@ -22,6 +22,20 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`songxmlhandler` module provides the XML functionality for songs
+
+The basic XML is of the format::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <song version="1.0">
+        <lyrics language="en">
+            <verse type="chorus" label="1">
+                <![CDATA[ ... ]]>
+            </verse>
+        </lyrics>
+    </song>
+"""
 
 import logging
 
@@ -34,17 +48,6 @@ log = logging.getLogger(__name__)
 class SongXMLBuilder(object):
     """
     This class builds the XML used to describe songs.
-
-    The basic XML looks like this::
-
-        <?xml version="1.0" encoding="UTF-8"?>
-        <song version="1.0">
-          <lyrics language="en">
-            <verse type="chorus" label="1">
-              <![CDATA[ ... ]]>
-            </verse>
-          </lyrics>
-        </song>
     """
     log.info(u'SongXMLBuilder Loaded')
 
@@ -113,17 +116,6 @@ class SongXMLBuilder(object):
 class SongXMLParser(object):
     """
     A class to read in and parse a song's XML.
-
-    The basic XML looks like this::
-
-        <?xml version="1.0" encoding="UTF-8"?>
-        <song version="1.0">
-          <lyrics language="en">
-            <verse type="chorus" label="1">
-              <![CDATA[ ... ]]>
-            </verse>
-          </lyrics>
-        </song>
     """
     log.info(u'SongXMLParser Loaded')
 

openlp/core/ui/mediadockmanager.py

@@ -28,11 +28,25 @@ import logging
 log = logging.getLogger(__name__)
 
 class MediaDockManager(object):
-
+    """
+    Provide a repository for MediaManagerItems
+    """
     def __init__(self, media_dock):
+        """
+        Initialise the media dock
+        """
         self.media_dock = media_dock
 
     def add_dock(self, media_item, icon, weight):
+        """
+        Add a MediaManagerItem to the dock
+
+        ``media_item``
+            The item to add to the dock
+
+        ``icon``
+            An icon for this dock item
+        """
         log.info(u'Adding %s dock' % media_item.title)
         self.media_dock.addItem(media_item, icon, media_item.title)
 
@@ -53,6 +67,12 @@ class MediaDockManager(object):
             self.media_dock.addItem(media_item, icon, media_item.title)
 
     def remove_dock(self, name):
+        """
+        Removes a MediaManagerItem from the dock
+
+        ``name``
+            The item to remove
+        """
         log.debug(u'remove %s dock' % name)
         for dock_index in range(0, self.media_dock.count()):
             if self.media_dock.widget(dock_index):

openlp/core/ui/screen.py

@@ -22,7 +22,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
-
+"""
+The :mod:`screen` module provides management functionality for a machines'
+displays
+"""
 import logging
 import copy
 
@@ -46,12 +49,18 @@ class ScreenList(object):
         self.monitor_number = 0
 
     def add_screen(self, screen):
+        """
+        Add a screen to the list of known screens
+        """
         if screen[u'primary']:
             self.current = screen
         self.screen_list.append(screen)
         self.display_count += 1
 
     def screen_exists(self, number):
+        """
+        Confirms a screen is known
+        """
         for screen in self.screen_list:
             if screen[u'number'] == number:
                 return True

openlp/core/ui/settingsform.py

@@ -22,7 +22,9 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
-
+"""
+The :mod:`settingsform` provides a user interface for the OpenLP settings
+"""
 import logging
 
 from PyQt4 import QtGui
@@ -33,8 +35,13 @@ from settingsdialog import Ui_SettingsDialog
 log = logging.getLogger(__name__)
 
 class SettingsForm(QtGui.QDialog, Ui_SettingsDialog):
-
+    """
+    Provide the form to manipulate the settings for OpenLP
+    """
     def __init__(self, screens, mainWindow, parent=None):
+        """
+        Initialise the settings form
+        """
         QtGui.QDialog.__init__(self, parent)
         self.setupUi(self)
         # General tab
@@ -48,16 +55,25 @@ class SettingsForm(QtGui.QDialog, Ui_SettingsDialog):
         self.addTab(u'Display', self.DisplayTab)
 
     def addTab(self, name, tab):
+        """
+        Add a tab to the form
+        """
         log.info(u'Adding %s tab' % tab.tabTitle)
         self.SettingsTabWidget.addTab(tab, tab.tabTitleVisible)
 
     def insertTab(self, tab, location):
+        """
+        Add a tab to the form at a specific location
+        """
         log.debug(u'Inserting %s tab' % tab.tabTitle)
         #13 : There are 3 tables currently and locations starts at -10
         self.SettingsTabWidget.insertTab(
             location + 13, tab, tab.tabTitleVisible)
 
     def removeTab(self, name):
+        """
+        Remove a tab from the form
+        """
         log.debug(u'remove %s tab' % name)
         for tab_index in range(0, self.SettingsTabWidget.count()):
             if self.SettingsTabWidget.widget(tab_index):
@@ -65,10 +81,16 @@ class SettingsForm(QtGui.QDialog, Ui_SettingsDialog):
                     self.SettingsTabWidget.removeTab(tab_index)
 
     def accept(self):
+        """
+        Process the form saving the settings
+        """
         for tab_index in range(0, self.SettingsTabWidget.count()):
             self.SettingsTabWidget.widget(tab_index).save()
         return QtGui.QDialog.accept(self)
 
     def postSetUp(self):
+        """
+        Run any post-setup code for the tabs on the form
+        """
         for tab_index in range(0, self.SettingsTabWidget.count()):
             self.SettingsTabWidget.widget(tab_index).postSetUp()

openlp/plugins/alerts/__init__.py

@@ -22,3 +22,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`alerts` module provides the Alerts plugin for producing impromptu
+on-screen announcements during a service
+"""

openlp/plugins/bibles/__init__.py

@@ -22,3 +22,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`bibles' modules provides the Bible plugin to enable OpenLP to display
+scripture
+"""