From b984a445d59e24b872099c9df99341a97996cfaf Mon Sep 17 00:00:00 2001
From: Timo Stollenwerk <timo@zmag.de>
Date: Tue, 5 Oct 2010 15:14:12 +0000
Subject: [PATCH] Inline documentation for moderation view added.

svn path=/plone.app.discussion/trunk/; revision=40517
---
 plone/app/discussion/browser/moderation.py | 74 +++++++++++++++++++++-
 1 file changed, 71 insertions(+), 3 deletions(-)

diff --git a/plone/app/discussion/browser/moderation.py b/plone/app/discussion/browser/moderation.py
index a4c4e86..c0726c4 100644
--- a/plone/app/discussion/browser/moderation.py
+++ b/plone/app/discussion/browser/moderation.py
@@ -33,7 +33,7 @@ ZopeTwoPageTemplateFile._getContext = _getContext # pragma: no cover
 
 
 class View(BrowserView):
-    """Moderation View
+    """Main moderation View.
     """
 
     template = ViewPageTemplateFile('moderation.pt')
@@ -74,7 +74,24 @@ class View(BrowserView):
 
 
 class DeleteComment(BrowserView):
-    """Delete a comment from a conversation
+    """Delete a comment from a conversation.
+    
+       This view is always called directly on the comment object:
+       
+         http://nohost/front-page/++conversation++default/1286289644723317/\
+         @@moderate-delete-comment
+
+       Each table row (comment) in the moderation view contains a hidden input
+       field with the absolute URL of the content object:
+       
+         <input type="hidden" 
+                value="http://nohost/front-page/++conversation++default/\
+                       1286289644723317" 
+                name="selected_obj_paths:list">
+        
+       This absolute URL is called from a jQuery method that is bind to the
+       'delete' button of the table row. See javascripts/moderation.js for more
+       details.       
     """
 
     def __call__(self):
@@ -93,8 +110,26 @@ class DeleteComment(BrowserView):
         return self.context.REQUEST.RESPONSE.redirect(
             self.context.REQUEST.HTTP_REFERER)
 
+
 class PublishComment(BrowserView):
-    """Publish a comment
+    """Publish a comment.
+    
+       This view is always called directly on the comment object:
+       
+           http://nohost/front-page/++conversation++default/1286289644723317/\
+           @@moderate-publish-comment
+
+       Each table row (comment) in the moderation view contains a hidden input
+       field with the absolute URL of the content object:
+       
+         <input type="hidden" 
+                value="http://nohost/front-page/++conversation++default/\
+                       1286289644723317" 
+                name="selected_obj_paths:list">
+        
+       This absolute URL is called from a jQuery method that is bind to the
+       'delete' button of the table row. See javascripts/moderation.js for more
+       details.               
     """
 
     def __call__(self):
@@ -117,6 +152,25 @@ class PublishComment(BrowserView):
 
 class BulkActionsView(BrowserView):
     """Bulk actions (unapprove, approve, delete, mark as spam).
+    
+       Each table row of the moderation view has a checkbox with the absolute 
+       path (without host and port) of the comment objects:
+       
+         <input type="checkbox"
+                name="paths:list"
+                value="/plone/front-page/++conversation++default/\
+                       1286289644723317" 
+                id="cb_1286289644723317" />
+       
+       If checked, the comment path will occur in the 'paths' variable of 
+       the request when the bulk actions view is called. The bulk action 
+       (delete, publish, etc.) will be applied to all comments that are 
+       included.
+       
+       The paths have to be 'traversable':
+       
+         /plone/front-page/++conversation++default/1286289644723317                
+
     """
 
     def __call__(self):
@@ -145,6 +199,13 @@ class BulkActionsView(BrowserView):
         raise NotImplementedError
 
     def publish(self):
+        """Publishes all comments in the paths variable.
+        
+           Expects a list of absolute paths (without host and port):
+        
+             /Plone/startseite/++conversation++default/1286200010610352
+           
+        """
         context = aq_inner(self.context)
         for path in self.paths:
             comment = context.restrictedTraverse(path)
@@ -159,6 +220,13 @@ class BulkActionsView(BrowserView):
         raise NotImplementedError
 
     def delete(self):
+        """Deletes all comments in the paths variable.
+        
+           Expects a list of absolute paths (without host and port):
+        
+             /Plone/startseite/++conversation++default/1286200010610352
+           
+        """        
         context = aq_inner(self.context)
         for path in self.paths:
             comment = context.restrictedTraverse(path)