add more docstring for "poll" module

common/lib/xmodule/xmodule/poll_module.py

 """Poll module is ungraded xmodule used by students to
 to do set of polls.
 
-Poll module contains a nummber of 2 - steps basic sequences. Every sequence
-has data from all previous sequences. Selection of sequences can be in
-control block.
+On the client side we show:
+If student does not yet anwered - Question with set of choices.
+If student have answered - Question with statistics for each answers.
 
-Basic sequence:
-`
-0. Control block
-    a) get data from any previous sequence
-    b) if block
-    c) link to sequence
-
-
-1. First. - must be, always visible
-If student does not yet anwered - Question
-If student have not answered - Question with statistics (yes/no)
-
-2. Second - optional, if student does not yet answered on 1st - hidden
-If student answers first time - show plot with statistics from
-answer from other users.
+Student can't change his answer.
 
 """
 
-
 import cgi
 import json
 import logging
@@ -52,36 +37,40 @@ class PollModule(XModule):
     css = {'scss': [resource_string(__name__, 'css/poll/display.scss')]}
     js_module_name = "Poll"
 
-    # name of poll to use in links to this poll
+    # Name of poll to use in links to this poll
     display_name = String(help="Display name for this module", scope=Scope.settings)
 
     voted = Boolean(help="Whether this student has voted on the poll", scope=Scope.student_state, default=False)
     poll_answer = String(help="Student answer", scope=Scope.student_state, default='')
-    poll_answers = Object(help="All possible answers for the poll", scope=Scope.content, default={})
+    poll_answers = Object(help="All possible answers for the poll fro other students", scope=Scope.content, default={})
 
-    answers = List(help="Poll answers", scope=Scope.content, default=[])
+    answers = List(help="Poll answers from xml", scope=Scope.content, default=[])
     question = String(help="Poll question", scope=Scope.content, default='')
 
     def handle_ajax(self, dispatch, get):
         """Ajax handler.
 
         Args:
-            dispatch: request slug
-            get: request get parameters
+            dispatch: string request slug
+            get: dict request get parameters
 
         Returns:
-            dict
+            json string
         """
         if dispatch in self.poll_answers and not self.voted:
+            # FIXME: fix this, when xblock support mutable types.
+            # Now we use this hack.
             temp_poll_answers = self.poll_answers
             temp_poll_answers[dispatch] += 1
+            self.poll_answers = temp_poll_answers
+
             self.voted = True
             self.poll_answer = dispatch
-            self.poll_answers = temp_poll_answers
             return json.dumps({'poll_answers': self.poll_answers,
                                'total': sum(self.poll_answers.values()),
                                'callback': {'objectName': 'Conditional'}
                                })
+        # return error message
         return json.dumps({'error': 'Unknown Command!'})
 
     def get_html(self):
@@ -102,14 +91,19 @@ class PollModule(XModule):
             string - Serialize json.
         """
         answers_to_json = {}
-        #workaround
+
+        # FIXME: fix this, when xblock support mutable types.
+        # Now we use this hack.
         temp_poll_answers = self.poll_answers
+
          # Fill self.poll_answers, prepare data for template context.
         for answer in self.answers:
+            # Set default count for answer = 0.
             if answer['id'] not in temp_poll_answers:
                 temp_poll_answers[answer['id']] = 0
             answers_to_json[answer['id']] = cgi.escape(answer['text'])
         self.poll_answers = temp_poll_answers
+
         return json.dumps({'answers': answers_to_json,
             'question': cgi.escape(self.question),
             # to show answered poll after reload:
@@ -119,6 +113,9 @@ class PollModule(XModule):
 
 
 class PollDescriptor(MakoModuleDescriptor, XmlDescriptor):
+    _tag_name = 'poll_question'
+    _child_tag_name = 'answer'
+
     module_class = PollModule
     template_dir_name = 'poll'
     stores_state = True
@@ -138,17 +135,20 @@ class PollDescriptor(MakoModuleDescriptor, XmlDescriptor):
 
         Returns:
             (definition, children) - tuple
-            definition - dict
-            children - list
+            definition - dict:
+                {
+                    'answers': <List of answers>,
+                    'question': <Question string>
+                }
         """
-        # check for presense of required tags in xml
-        if len(xml_object.xpath('answer')) == 0:
+        # Check for presense of required tags in xml.
+        if len(xml_object.xpath(cls._child_tag_name)) == 0:
             raise ValueError("Poll_question definition must include \
                 at least one 'answer' tag")
 
         xml_object_copy = deepcopy(xml_object)
         answers = []
-        for element_answer in xml_object_copy.findall('answer'):
+        for element_answer in xml_object_copy.findall(cls._child_tag_name):
             answer_id = element_answer.get('id', None)
             if answer_id:
                 answers.append({
@@ -166,15 +166,17 @@ class PollDescriptor(MakoModuleDescriptor, XmlDescriptor):
         return (definition, children)
 
     def definition_to_xml(self, resource_fs):
-        """Return an xml element representing this definition."""
-        poll_str = '<poll_question>{0}</poll_question>'.format(self.question)
+        """Return an xml element representing to this definition."""
+        poll_str = '<{tag_name}>{text}</{tag_name}>'.format(
+            tag_name=self._tag_name, text=self.question)
         xml_object = etree.fromstring(poll_str)
         xml_object.set('display_name', self.display_name)
         xml_object.set('id', self.id)
 
         def add_child(xml_obj, answer):
-            child_str = '<answer id="{id}">{text}</answer>'.format(
-                id=answer['id'], text=answer['text'])
+            child_str = '<{tag_name} id="{id}">{text}</{tag_name}>'.format(
+                tag_name=self._child_tag_name, id=answer['id'],
+                text=answer['text'])
             child_node = etree.fromstring(child_str)
             xml_object.append(child_node)