I did some more code-keeping in this commit. I added a lot of documentation, so

that most of my functions do indeed have effective docstrings. I also changed
the decorators so that they imply eachother in a logical way. I also modified
the one decorator get_media_comment_by_id to be more usable with the variable
urls of mediagoblin.user_pages.views:file_a_report. I also noticed a few tests
had broken, so I went through them and fixed them up, finding that mostly there
were problems in my actual writing of the tests. I also did a few other small
tasks such as creating a new User method to check whether or not a User is ban-
-ned.

===============================================================================
    Added in documentation
===============================================================================
--\  mediagoblin/db/models.py
--\  mediagoblin/decorators.py
--\  mediagoblin/moderation/forms.py
--\  mediagoblin/moderation/tools.py
--\  mediagoblin/moderation/views.py
--\  mediagoblin/user_pages/lib.py

===============================================================================
    Rearranged decorators to be more efficient
===============================================================================
--\  mediagoblin/decorators.py
--| Made it so that user_not_banned is encapsulated in require_active_login
--| Made it so that require_active_login is encapsulated in user_has_privilege
--| Changed get_media_comment_by_id into get_optional_media_comment_by_id. It
  | now returns valid code if the MediaComment id is absent. This makes it pos-
  | -sible to use this decorator for the function:
  |         mediagoblin.user_pages.views:file_a_report

--\  mediagoblin/user_pages/views.py
--| Replaced the mediagoblin.user_pages.views:file_a_comment_report with the
  | decorator mentioned above

--\  mediagoblin/user_pages/routing.py

        -----------------------------------------------------------
        |     took out unnecessary @user_not_banned decorators    |
        -----------------------------------------------------------
--\  mediagoblin/submit/views.py
--\  mediagoblin/user_pages/views.py

===============================================================================
    Fixed broken tests
===============================================================================
--\  mediagoblin/tests/test_auth.py
--\  mediagoblin/tests/test_privileges.py
--\  mediagoblin/tests/test_submission.py

===============================================================================
    Fixed broken code
===============================================================================
--\  mediagoblin/tools/response.py

===============================================================================
    Other Tasks
===============================================================================
--\  mediagoblin/db/models.py
--| Added in User.is_banned() method
--\  mediagoblin/decorators.py
--| Utitilized User.is_banned() method in the user_not_banned decorator

--\  mediagoblin/moderation/views.py
--| Made it impossible for an admin to ban themself.
--| Got rid of a vestigial print statement

--\  mediagoblin/templates/mediagoblin/base.html
--| Made it so the top panel does not show up for users that are banned.

--\  mediagoblin/templates/mediagoblin/moderation/user.html
--| Rearranged the javascript slightly

===============================================================================

1 files changed, 16 insertions, 6 deletions

diff --git a/mediagoblin/user_pages/lib.py b/mediagoblin/user_pages/lib.py
index f29c1796..80eb30bd 100644
--- a/mediagoblin/user_pages/lib.py
+++ b/mediagoblin/user_pages/lib.py
@@ -83,12 +83,22 @@ def build_report_object(report_form, media_entry=None, comment=None):
     This function is used to convert a form object (from a User filing a
         report) into either a MediaReport or CommentReport object.
 
-    :param report_form should be a MediaReportForm or a CommentReportForm
-        object
-    :param
-
-    :returns either of MediaReport or a CommentReport object that has not been
-        saved. In case of an improper form_dict, returns None
+    :param report_form          A MediaReportForm or a CommentReportForm object
+                                  with valid information from a POST request.
+    :param media_entry          A MediaEntry object. The MediaEntry being repo-
+                                  -rted by a MediaReport. In a CommentReport,
+                                  this will be None.
+    :param comment              A MediaComment object. The MediaComment being 
+                                  reported by a CommentReport. In a MediaReport
+                                  this will be None.
+
+    :returns                A MediaReport object if a valid MediaReportForm is
+                              passed as kwarg media_entry. This MediaReport has
+                              not been saved.
+    :returns                A CommentReport object if a valid CommentReportForm
+                              is passed as kwarg comment. This CommentReport
+                              has not been saved.
+    :returns                None if the form_dict is invalid.
     """
 
     if report_form.validate() and comment is not None: