Fix oppia#2394: add docstrings to core/domain/stats_jobs_one_off.py (o…

…ppia#3461)

* statistic audit docstring

* statistics audit docstring

* statistics audit docstring

* answers audit docstring

* answers audit 2 docs

* partial answers validation audit doc

* ruletype breakdown audit docs

* cleaning

* clear unknown missing answers docs

* clear migrated answers job docs

* purge inconsistent answers job docs

* split large answer buckets job docs

* clear large answer buckets job

* cleanup large bucket labels from new answers job docs

* answer migration validation job docs

* cleaning

* answer migration cleanup job docs

* refresh interaction registry job docs

* answer migration job docs

* cleaning

* formatting

* formatting

* formatting

* formatting

* formatting

* Fix oppia#2394: add more type information; cleaning

* Fix oppia#2394: add more type information; cleaning

* Fix oppia#2394: add type information

core/domain/stats_jobs_one_off.py

@@ -27,7 +27,9 @@
 
 
 class StatisticsAudit(jobs.BaseMapReduceJobManager):
-    """Performs a brief audit of exploration completions and state hit counts to
+    """A one-off statistics audit.
+
+    Performs a brief audit of exploration completions and state hit counts to
     make sure they match counts stored in StateCounterModel. It also checks for
     some possible error cases like negative counts.
     """
@@ -41,6 +43,39 @@ def entity_classes_to_map_over(cls):
 
     @staticmethod
     def map(item):
+        """Implements the map function. Must be declared @staticmethod.
+
+        Args:
+            item: ExplorationAnnotationsModel or
+                StateCounterModel.
+
+        Yields:
+            tuple. For StateCounterModel, a 2-tuple in the form
+                (_STATE_COUNTER_ERROR_KEY, error message).
+            tuple. For ExplorationAnnotationModel, a 2-tuple in the form
+                ('exploration_id', value).
+                'exploration_id': str. the id of the exploration.
+                'value': a dict, whose structure is as follows:
+                    {
+                        'version': str. version of the exploration.
+                        'starts': int. # of times exploration was started.
+                        'completions': int. # of times exploration was
+                            completed.
+                        'state_hit': a dict containing the hit counts for the
+                            states in the exploration. It is formatted as
+                            follows:
+                            {
+                                state_name: {
+                                    'first_entry_count': int. # of sessions
+                                        which hit this state.
+                                    'total_entry_count': int. # of total hits
+                                        for this state.
+                                    'no_answer_count': int. # of hits with no
+                                        answer for this state.
+                                }
+                            }
+                    }
+        """
         if isinstance(item, stats_models.StateCounterModel):
             if item.first_entry_count < 0:
                 yield (
@@ -60,6 +95,36 @@ def map(item):
 
     @staticmethod
     def reduce(key, stringified_values):
+        """Updates statistics for the given exploration.
+
+        Args:
+            key: str. The id of the exploration.
+            stringified_values: list(str). A list of stringified values
+                associated with the given key. An element of stringified_values
+                would be of the form:
+                    {
+                        'version': str. version of the exploration.
+                        'starts': int. # of times exploration was started.
+                        'completions': int. # of times exploration was
+                            completed.
+                        'state_hit': dict. a dict containing the hit counts
+                            for the states in the exploration. It is formatted
+                            as follows:
+                            {
+                                state_name: {
+                                    'first_entry_count': int. # of sessions
+                                        which hit this state.
+                                    'total_entry_count': int. # of total
+                                        hits for this state.
+                                    'no_answer_count': int. # of hits with
+                                        no answer for this state.
+                                }
+                            }
+                    }
+
+        Yields:
+            tuple(str). A 1-tuple whose only element is an error message.
+        """
         if key == StatisticsAudit._STATE_COUNTER_ERROR_KEY:
             for value_str in stringified_values:
                 yield (value_str,)