[#2959] Comments and docstrings

ckan/lib/search/__init__.py

@@ -116,14 +116,20 @@ class SynchronousSearchPlugin(SingletonPlugin):
 
     def notify(self, entity, operation):
 
+        ## If a Group's name hsa been changed, then its datasets need to be
+        ## re-indexed.
         if (isinstance(entity, model.Group) and
                 operation == domain_object.DomainObjectOperation.changed):
+
+            ## Check if the name has changed.
             if 'name' in entity.diff():
                 for dataset in entity.active_packages().all():
                     dispatch_by_operation(
                             dataset.__class__.__name__,
                             get_action('package_show')(
-                                {'model': model, 'ignore_auth': True, 'validate': False},
+                                {'model': model,
+                                 'ignore_auth': True,
+                                 'validate': False},
                                 {'id': dataset.id}),
                             operation
                     )

ckan/plugins/interfaces.py

@@ -175,10 +175,20 @@ def after_rollback(self, session):
 
 class IDomainObjectModification(Interface):
     """
-    Receives notification of new, changed and deleted datesets.
+    Receives notification of new, changed and deleted Package, Resource and
+    Group objects.
     """
 
     def notify(self, entity, operation):
+        '''Called when a domain model is created/updated/deleted.
+
+        entity - the instance of the Package, Resource or Group that has been
+                 created/updated/deleted.
+
+        operation - instance of `domain_object.DomainObjectOperation`
+                    identifying whether the `entity` was created, updated or
+                    deleted.
+        '''
         pass