Improve gen documentation

gramps/gen/recentfiles.py

@@ -57,7 +57,7 @@ MAX_GRAMPS_ITEMS = 10
 #-------------------------------------------------------------------------
 class RecentItem(object):
     """
-    Interface to a single GRAMPS recent-items item
+    Interface to a single Gramps recent-items item
     """
 
     def __init__(self,p="", n="",t=0):
@@ -182,7 +182,7 @@ class RecentFiles(object):
 
     def do_save(self):
         """
-        Saves the current GRAMPS RecentFiles collection to the associated file.
+        Saves the current Gramps RecentFiles collection to the associated file.
         """
         xml_file = open(os.path.expanduser(GRAMPS_FILENAME),'w')
 
@@ -281,7 +281,7 @@ class RecentParser(object):
 #-------------------------------------------------------------------------
 def recent_files(filename, name):
     """
-    Add an entry to both GNOME and GRAMPS recent-items storages.
+    Add an entry to both GNOME and Gramps recent-items storages.
     """
 
     the_time = int(time.time())

gramps/gen/sort.py

@@ -21,7 +21,7 @@
 # $Id$
 
 """
-Provide sorting routines for use in GRAMPS. Since these functions are
+Provide sorting routines for use in Gramps. Since these functions are
 intended to provide fast sorting, they tend to bypass access methods, 
 and directly use class members. For this reason, care needs to be taken
 to make sure these remain in sync with the rest of the design.
@@ -77,8 +77,10 @@ class Sort(object):
 ##            return glocale.strcoll(fsn, ssn)
 
     def by_last_name_key(self, first_id):
-        """Sort routine for comparing two last names. If last names are equal, 
+        """
-        uses the given name and suffix"""
+        Sort routine for comparing two last names. If last names are equal, 
+        uses the given name and suffix
+        """
         first = self.database.get_person_from_handle(first_id)
         
         name1 = first.get_primary_name()
@@ -139,8 +141,10 @@ class Sort(object):
 ##        return val
 
     def by_birthdate_key(self, first_id):
-        """Sort routine for comparing two people by birth dates. If the birth dates
+        """
-        are equal, sorts by name"""
+        Sort routine for comparing two people by birth dates. If the birth dates
+        are equal, sorts by name
+        """
         first = self.database.get_person_from_handle(first_id)
 
         birth1 = get_birth_or_fallback(self.database, first)

gramps/gen/updatecallback.py

@@ -21,11 +21,11 @@
 # $Id$
 
 """
-A set of basic utilities that everything in GRAMPS can depend upon.
+A set of basic utilities that everything in Gramps can depend upon.
 
 The goal is to have this module not depend on any other gramps module.
 That way, e.g. database classes can safely depend on that without
-other GRAMPS baggage.
+other Gramps baggage.
 """
 from __future__ import division
 #-------------------------------------------------------------------------
@@ -50,10 +50,10 @@ class UpdateCallback(object):
 
     def __init__(self, callback, interval=1):
         """
-        @param callback: a function with one arg to execute every so often
+        :param callback: a function with one arg to execute every so often
-        @type callback: function
+        :type callback: function
-        @param interval: number of seconds at most between the updates
+        :param interval: number of seconds at most between the updates
-        @type interval: int
+        :type interval: int
         """
         if isinstance(callback, collections.Callable): # callback is really callable
             self.update = self.update_real

gramps/gen/user.py

@@ -45,15 +45,15 @@ class User():
 
         Don't use this method directly, use progress instead.
         
-        @param title: the title of the progress meter
+        :param title: the title of the progress meter
-        @type title: str
+        :type title: str
-        @param message: the message associated with the progress meter
+        :param message: the message associated with the progress meter
-        @type message: str
+        :type message: str
-        @param steps: the total number of steps for the progress meter.
+        :param steps: the total number of steps for the progress meter.
             a value of 0 indicates that the ending is unknown and the
             meter should just show activity.
-        @type steps: int
+        :type steps: int
-        @returns: none
+        :returns: none
         """
         pass
     
@@ -99,7 +99,8 @@ class User():
 
         Parameters: same as for begin_progress.
         
-        Usage example (see gramps/cli/test/user_test.py):
+        Usage example (see gramps/cli/test/user_test.py)::
+
             with self.user.progress("Foo", "Bar", 0) as step:
                 for i in range(10):
                     step()
@@ -118,18 +119,18 @@ class User():
         """
         Prompt the user with a message to select an alternative.
         
-        @param title: the title of the question, e.g.: "Undo history warning"
+        :param title: the title of the question, e.g.: "Undo history warning"
-        @type title: str
+        :type title: str
-        @param message: the message, e.g.: "Proceeding with the tool will
+        :param message: the message, e.g.: "Proceeding with the tool will
             erase the undo history. If you think you may want to revert
             running this tool, please stop here and make a backup of the DB."
-        @type question: str
+        :type question: str
-        @param accept_label: what to call the positive choice, e.g.: "Proceed"
+        :param accept_label: what to call the positive choice, e.g.: "Proceed"
-        @type accept_label: str
+        :type accept_label: str
-        @param reject_label: what to call the negative choice, e.g.: "Stop"
+        :param reject_label: what to call the negative choice, e.g.: "Stop"
-        @type reject_label: str
+        :type reject_label: str
-        @returns: the user's answer to the question
+        :returns: the user's answer to the question
-        @rtype: bool
+        :rtype: bool
         """
         return False
     
@@ -137,11 +138,11 @@ class User():
         """
         Warn the user.
         
-        @param title: the title of the warning
+        :param title: the title of the warning
-        @type title: str
+        :type title: str
-        @param warning: the warning
+        :param warning: the warning
-        @type warning: str
+        :type warning: str
-        @returns: none
+        :returns: none
         """
         pass
     
@@ -149,11 +150,11 @@ class User():
         """
         Notify the user of an error.
         
-        @param title: the title of the error
+        :param title: the title of the error
-        @type title: str
+        :type title: str
-        @param error: the error message
+        :param error: the error message
-        @type error: str
+        :type error: str
-        @returns: none
+        :returns: none
         """
         pass
 
@@ -161,9 +162,9 @@ class User():
         """
         Notify the user of a DB error.
         
-        @param error: the error message
+        :param error: the error message
-        @type error: str
+        :type error: str
-        @returns: none
+        :returns: none
         """
         pass