From 818e46fba7374f5011d351dfb01511fb36e620e3 Mon Sep 17 00:00:00 2001
From: Samuel Findlay <samuel.findlay@gmail.com>
Date: Wed, 6 Jun 2012 19:14:53 +1000
Subject: [PATCH] Formatting and comments

---
 openlp/plugins/songs/forms/songimportform.py | 17 +++---
 openlp/plugins/songs/lib/importer.py         | 59 +++++++++++++-------
 2 files changed, 47 insertions(+), 29 deletions(-)

diff --git a/openlp/plugins/songs/forms/songimportform.py b/openlp/plugins/songs/forms/songimportform.py
index 4837a4b5a..b13056b32 100644
--- a/openlp/plugins/songs/forms/songimportform.py
+++ b/openlp/plugins/songs/forms/songimportform.py
@@ -217,8 +217,7 @@ class SongImportForm(OpenLPWizard):
     def validateCurrentPage(self):
         """
         Validate the current page before moving on to the next page.
-
-        Provides each song format class with a chance to validate its input by
+        Provide each song format class with a chance to validate its input by
         overriding isValidSource().
         """
         if self.currentPage() == self.welcomePage:
@@ -491,16 +490,16 @@ class SongImportForm(OpenLPWizard):
 
 class SongImportSourcePage(QtGui.QWizardPage):
     """
-    Subclass QtGui.QWizardPage in order to reimplement isComplete().
+    Subclass of QtGui.QWizardPage to override isComplete() for Source Page.
     """
-
     def isComplete(self):
         """
-        Returns True if:
-            * an available format is selected, and
-            * if MultipleFiles mode, at least one file is selected
-            * or if SingleFile mode, the specified file exists
-            * or if SingleFolder mode, the specified folder exists
+        Return True if:
+
+        * an available format is selected, and
+        * if MultipleFiles mode, at least one file is selected
+        * or if SingleFile mode, the specified file exists
+        * or if SingleFolder mode, the specified folder exists
 
         When this method returns True, the wizard's Next button is enabled.
         """
diff --git a/openlp/plugins/songs/lib/importer.py b/openlp/plugins/songs/lib/importer.py
index c13ce8038..11169813b 100644
--- a/openlp/plugins/songs/lib/importer.py
+++ b/openlp/plugins/songs/lib/importer.py
@@ -79,28 +79,47 @@ class SongFormat(object):
     song formats handled by the importer, the attributes of each song format,
     and a few helper functions.
 
-
     Required attributes for each song format:
-    * ``Class`` Import class, e.g. OpenLyricsImport
-    * ``Name`` Name of the format, e.g. u'OpenLyrics'
-    * ``Prefix`` Prefix for Qt objects. Use camelCase, e.g. u'openLyrics'
-      See ``SongImportForm.addFileSelectItem()``.
+
+    ``Class``
+        Import class, e.g. ``OpenLyricsImport``
+    ``Name``
+        Name of the format, e.g. ``u'OpenLyrics'``
+    ``Prefix``
+        Prefix for Qt objects. Use mixedCase, e.g. ``u'openLyrics'``
+        See ``SongImportForm.addFileSelectItem()``
 
     Optional attributes for each song format:
-    * ``CanDisable`` Whether song format importer is disablable.
-    * ``Availability`` Whether song format importer is available.
-    * ``SelectMode`` Whether format accepts single file, multiple files, or
-      single folder (as per SongFormatSelect options).
-    * ``Filter`` File extension filter for QFileDialog.
 
-    Optional/custom text Strings for SongImportForm widgets:
-    * ``ComboBoxText`` Combo box selector (default value is format Name).
-    * ``DisabledLabelText`` Required for disablable song formats.
-    * ``GetFilesTitle`` Title for QFileDialog (default includes format Name).
-    * ``InvalidSourceMsg`` Message displayed when source does not validate with
-      Class.isValidSource().
+    ``CanDisable``
+        Whether song format importer is disablable.
+    ``Availability``
+        Whether song format importer is available.
+    ``SelectMode``
+        Whether format accepts single file, multiple files, or single folder
+        (as per ``SongFormatSelect`` options).
+    ``Filter``
+        File extension filter for ``QFileDialog``.
+
+    Optional/custom text Strings for ``SongImportForm`` widgets:
+
+    ``ComboBoxText``
+        Combo box selector (default value is the format's ``Name``).
+    ``DisabledLabelText``
+        Required for disablable song formats.
+    ``GetFilesTitle``
+        Title for ``QFileDialog`` (default includes the format's ``Name``).
+    ``InvalidSourceMsg``
+        Message displayed if ``Class.isValidSource()`` returns ``False``.
     """
-    # Song Formats
+    # Enumeration of song formats and their attributes
+    # * Numerical order of song formats is significant as it determines the
+    #   order used by formatComboBox.
+    # * Attribute ints are negative so they don't clash with song format ints.
+    # * Each group of attribute values increments by 10 to facilitate addition
+    #   of more attributes in future.
+
+    # Song formats (ordered alphabetically after Generic)
     Unknown = -1
     OpenLyrics = 0
     OpenLP2 = 1
@@ -309,9 +328,9 @@ class SongFormat(object):
             Zero or more song format attributes from SongFormat.
 
         Return type depends on number of supplied attributes:
-            * 0 : Return dict containing all defined attributes for the format.
-            * 1 : Return the attribute value.
-            * >1 : Return tuple of requested attribute values.
+        :0: Return dict containing all defined attributes for the format.
+        :1: Return the attribute value.
+        :>1: Return tuple of requested attribute values.
         """
         if not attributes:
             return SongFormat._attributes.get(format)