Improved docstrings.

common/lib/xmodule/xmodule/crowdsource_hinter.py

@@ -182,9 +182,10 @@ class CrowdsourceHinterModule(CrowdsourceHinterFields, XModule):
         Args:
         `data` -- must be interpretable by answer_to_str.
         Output keys:
-            - 'best_hint' is the hint text with the most votes.
-            - 'rand_hint_1' and 'rand_hint_2' are two random hints to the answer in `data`.
+            - 'hints' is a list of hint strings to show to the user.
             - 'answer' is the parsed answer that was submitted.
+        Will record the user's wrong answer in user_submissions, and the hints shown
+        in previous_answers.
         """
         # First, validate our inputs.
         try:
@@ -251,6 +252,8 @@ class CrowdsourceHinterModule(CrowdsourceHinterFields, XModule):
         Output keys:
             - 'answer_to_hints': a nested dictionary.
               answer_to_hints[answer][hint_pk] returns the text of the hint.
+            - 'user_submissions': the same thing as self.user_submissions.  A list of
+              the answers that the user previously submitted.
         """
         # The student got it right.
         # Did he submit at least one wrong answer?

lms/djangoapps/instructor/hint_manager.py

 """
 Views for hint management.
 
-Along with the crowdsource_hinter xmodule, this code is still
-experimental, and should not be used in new courses, yet.
+Get to these views through courseurl/hint_manager.
+For example: https://courses.edx.org/courses/MITx/2.01x/2013_Spring/hint_manager
+
+These views will only be visible if MITX_FEATURES['ENABLE_HINTER_INSTRUCTOR_VIEW'] = True
 """
 
 import json
@@ -23,6 +25,9 @@ from xmodule.modulestore.django import modulestore
 
 @ensure_csrf_cookie
 def hint_manager(request, course_id):
+    """
+    The URL landing function for all calls to the hint manager, both POST and GET.
+    """
     try:
         get_course_with_access(request.user, course_id, 'staff', depth=None)
     except Http404:
@@ -172,7 +177,13 @@ def change_votes(request, course_id, field):
     Updates the number of votes.
 
     The numbered fields of `request.POST` contain [problem_id, answer, pk, new_votes] tuples.
-    - Very similar to `delete_hints`.  Is there a way to merge them?  Nah, too complicated.
+    See `delete_hints`.
+
+    Example `request.POST`:
+    {'op': 'delete_hints',
+     'field': 'mod_queue',
+      1: ['problem_whatever', '42.0', '3', 42],
+      2: ['problem_whatever', '32.5', '12', 9001]}
     """
 
     for key in request.POST:
@@ -233,6 +244,8 @@ def approve(request, course_id, field):
     hint list.  POST:
     op, field
     (some number) -> [problem, answer, pk]
+
+    The numbered fields are analogous to those in `delete_hints` and `change_votes`.
     """
 
     for key in request.POST: