Document self assessment

common/lib/xmodule/xmodule/open_ended_module.py

@@ -39,6 +39,14 @@ log = logging.getLogger("mitx.courseware")
 class OpenEndedModule(openendedchild.OpenEndedChild):
     """
     The open ended module supports all external open ended grader problems.
+    Sample XML file:
+    <openended min_score_to_attempt="1" max_score_to_attempt="1">
+        <openendedparam>
+            <initial_display>Enter essay here.</initial_display>
+            <answer_display>This is the answer.</answer_display>
+            <grader_payload>{"grader_settings" : "ml_grading.conf", "problem_id" : "6.002x/Welcome/OETest"}</grader_payload>
+        </openendedparam>
+    </openended>
     """
     def setup_response(self, system, location, definition, descriptor):
         """
@@ -562,7 +570,7 @@ class OpenEndedModule(openendedchild.OpenEndedChild):
 
 class OpenEndedDescriptor(XmlDescriptor, EditingDescriptor):
     """
-    Module for adding self assessment questions to courses
+    Module for adding open ended response questions to courses
     """
     mako_template = "widgets/html-edit.html"
     module_class = OpenEndedModule
@@ -578,12 +586,10 @@ class OpenEndedDescriptor(XmlDescriptor, EditingDescriptor):
     @classmethod
     def definition_from_xml(cls, xml_object, system):
         """
-        Pull out the rubric, prompt, and submitmessage into a dictionary.
+        Pull out the open ended parameters into a dictionary.
 
         Returns:
         {
-        'rubric': 'some-html',
-        'prompt': 'some-html',
         'oeparam': 'some-html'
         }
         """

common/lib/xmodule/xmodule/openendedchild.py

-"""
-A Self Assessment module that allows students to write open-ended responses,
-submit, then see a rubric and rate themselves.  Persists student supplied
-hints, answers, and assessment judgment (currently only correct/incorrect).
-Parses xml definition file--see below for exact format.
-"""
-
 import copy
 from fs.errors import ResourceNotFoundError
 import itertools
@@ -48,9 +41,9 @@ class OpenEndedChild():
 
     initial (prompt, textbox shown)
          |
-    assessing (read-only textbox, rubric + assessment input shown)
+    assessing (read-only textbox, rubric + assessment input shown for self assessment, response queued for open ended)
          |
-    request_hint (read-only textbox, read-only rubric and assessment, hint input box shown)
+    post_assessment (read-only textbox, read-only rubric and assessment, hint input box shown)
          |
     done (submitted msg, green checkmark, everything else read-only.  If attempts < max, shows
          a reset button that goes back to initial state.  Saves previous
@@ -69,6 +62,7 @@ class OpenEndedChild():
     POST_ASSESSMENT = 'post_assessment'
     DONE = 'done'
 
+    #This is used to tell students where they are at in the module
     HUMAN_NAMES={
         'initial' : 'Started',
         'assessing' : 'Being scored',
@@ -78,35 +72,6 @@ class OpenEndedChild():
 
     def __init__(self, system, location, definition, descriptor, static_data,
                  instance_state=None, shared_state=None, **kwargs):
-        """
-        Definition file should have 4 blocks -- prompt, rubric, submitmessage, hintprompt,
-        and two optional attributes:
-        attempts, which should be an integer that defaults to 1.
-        If it's > 1, the student will be able to re-submit after they see
-        the rubric.
-        max_score, which should be an integer that defaults to 1.
-        It defines the maximum number of points a student can get.  Assumed to be integer scale
-        from 0 to max_score, with an interval of 1.
-
-        Note: all the submissions are stored.
-
-        Sample file:
-
-        <selfassessment attempts="1" max_score="1">
-            <prompt>
-                Insert prompt text here.  (arbitrary html)
-            </prompt>
-            <rubric>
-                Insert grading rubric here.  (arbitrary html)
-            </rubric>
-            <hintprompt>
-                Please enter a hint below: (arbitrary html)
-            </hintprompt>
-            <submitmessage>
-                Thanks for submitting!  (arbitrary html)
-            </submitmessage>
-        </selfassessment>
-        """
 
         # Load instance state
         if instance_state is not None:

common/lib/xmodule/xmodule/self_assessment_module.py

-"""
-A Self Assessment module that allows students to write open-ended responses,
-submit, then see a rubric and rate themselves.  Persists student supplied
-hints, answers, and assessment judgment (currently only correct/incorrect).
-Parses xml definition file--see below for exact format.
-"""
-
 import copy
 from fs.errors import ResourceNotFoundError
 import itertools
@@ -31,14 +24,42 @@ import openendedchild
 log = logging.getLogger("mitx.courseware")
 
 class SelfAssessmentModule(openendedchild.OpenEndedChild):
-
+    """
+    A Self Assessment module that allows students to write open-ended responses,
+    submit, then see a rubric and rate themselves.  Persists student supplied
+    hints, answers, and assessment judgment (currently only correct/incorrect).
+    Parses xml definition file--see below for exact format.
+
+    Sample XML format:
+    <selfassessment>
+        <hintprompt>
+            What hint about this problem would you give to someone?
+        </hintprompt>
+        <submitmessage>
+            Save Succcesful.  Thanks for participating!
+        </submitmessage>
+    </selfassessment>
+    """
     def setup_response(self, system, location, definition, descriptor):
+        """
+        Sets up the module
+        @param system: Modulesystem
+        @param location: location, to let the module know where it is.
+        @param definition: XML definition of the module.
+        @param descriptor: SelfAssessmentDescriptor
+        @return: None
+        """
         self.submit_message = definition['submitmessage']
         self.hint_prompt = definition['hintprompt']
         self.prompt = stringify_children(self.prompt)
         self.rubric = stringify_children(self.rubric)
 
     def get_html(self, system):
+        """
+        Gets context and renders HTML that represents the module
+        @param system: Modulesystem
+        @return: Rendered HTML
+        """
         #set context variables and render template
         if self.state != self.INITIAL:
             latest = self.latest_answer()
@@ -266,8 +287,6 @@ class SelfAssessmentDescriptor(XmlDescriptor, EditingDescriptor):
 
         Returns:
         {
-        'rubric': 'some-html',
-        'prompt': 'some-html',
         'submitmessage': 'some-html'
         'hintprompt': 'some-html'
         }