Merge "Comments to docstrings for notification emit methods"

keystone/assignment/core.py

@@ -113,9 +113,16 @@ class Manager(manager.Manager):
             raise AssertionError(_('Project is disabled: %s') % project_id)
 
     @notifications.disabled(_PROJECT, public=False)
-    def _disable_project(self, tenant_id):
-        # Simply emit the notification so that the callback system can do the
-        # right thing.
+    def _disable_project(self, project_id):
+        """Emit a notification to the callback system project is been disabled.
+
+        This method, and associated callback listeners, removes the need for
+        making direct calls to other managers to take action (e.g. revoking
+        project scoped tokens) when a project is disabled.
+
+        :param project_id: project identifier
+        :type project_id: string
+        """
         pass
 
     @notifications.updated(_PROJECT)
@@ -339,8 +346,15 @@ class Manager(manager.Manager):
 
     @notifications.disabled('domain', public=False)
     def _disable_domain(self, domain_id):
-        # Simply emit the notification so that the callback system can do the
-        # right thing.
+        """Emit a notification to the callback system domain is been disabled.
+
+        This method, and associated callback listeners, removes the need for
+        making direct calls to other managers to take action (e.g. revoking
+        domain scoped tokens) when a domain is disabled.
+
+        :param domain_id: domain identifier
+        :type domain_id: string
+        """
         pass
 
     @notifications.updated('domain')

keystone/identity/core.py

@@ -738,8 +738,14 @@ class Manager(manager.Manager):
 
     @notifications.internal(notifications.INVALIDATE_USER_TOKEN_PERSISTENCE)
     def emit_invalidate_user_token_persistence(self, user_id):
-        # Simply emit that the user has been removed from a group so the
-        # callback system can do the right thing.
+        """Emit a notification to the callback system to revoke user tokens.
+
+        This method and associated callback listener removes the need for
+        making a direct call to another manager to delete and revoke tokens.
+
+        :param user_id: user identifier
+        :type user_id: string
+        """
         pass
 
     @manager.response_truncated