Add docstrings. (oppia#6035)

quantumferret · Dec 28, 2018 · ff94f82 · ff94f82
1 parent e6a1c2a
commit ff94f82
Show file tree

Hide file tree

Showing 10 changed files with 58 additions and 1 deletion.
diff --git a/core/domain/calculation_registry.py b/core/domain/calculation_registry.py
@@ -29,6 +29,7 @@ class Registry(object):
 
     @classmethod
     def _refresh_registry(cls):
+        """Refreshes the registry to add new visualization instances."""
         cls._calculations_dict.clear()
 
         # Add new visualization instances to the registry.

diff --git a/core/domain/classifier_services_test.py b/core/domain/classifier_services_test.py
@@ -45,6 +45,9 @@ def setUp(self):
         self._init_classify_inputs('16')
 
     def _init_classify_inputs(self, exploration_id):
+        """Initializes all the classification inputs of the exploration
+        corresponding to the given exploration id.
+        """
         test_exp_filepath = os.path.join(
             feconf.TESTS_DATA_DIR, 'string_classifier_test.yaml')
         yaml_content = utils.get_file_contents(test_exp_filepath)

diff --git a/core/domain/collection_services_test.py b/core/domain/collection_services_test.py
@@ -39,6 +39,7 @@
 
 # pylint: disable=protected-access
 def _count_at_least_editable_collection_summaries(user_id):
+    """Returns the count of collection summaries that are atleast editable."""
     return len(collection_services._get_collection_summary_dicts_from_models(
         collection_models.CollectionSummaryModel.get_at_least_editable(
             user_id=user_id)))
@@ -132,9 +133,15 @@ class CollectionProgressUnitTests(CollectionServicesUnitTests):
     EXP_ID_2 = '2_exploration_id'
 
     def _get_progress_model(self, user_id, collection_id):
+        """Returns the CollectionProgressModel for the given user id and
+        collection id.
+        """
         return user_models.CollectionProgressModel.get(user_id, collection_id)
 
     def _record_completion(self, user_id, collection_id, exploration_id):
+        """Records the played exploration in the collection by the user
+        corresponding to the given user id.
+        """
         collection_services.record_played_exploration_in_collection_context(
             user_id, collection_id, exploration_id)
 
@@ -334,6 +341,7 @@ def setUp(self):
 
 
     def _create_search_query(self, terms, categories):
+        """Returns the search query derived from terms and categories."""
         query = ' '.join(terms)
         if categories:
             query += ' category=(' + ' OR '.join([
@@ -1342,6 +1350,7 @@ def setUp(self):
         # puts to the event log are asynchronous.
         @transaction_services.toplevel_wrapper
         def populate_datastore():
+            """A top level wrapper to populate the datastore."""
             collection_1 = self.save_new_valid_collection(
                 self.COLLECTION_ID_1, self.albert_id)
 
@@ -1508,6 +1517,7 @@ def test_contributor_ids(self):
             [albert_id, bob_id])
 
     def _check_contributors_summary(self, collection_id, expected):
+        """Checks the contributors summary with the expected summary."""
         contributors_summary = collection_services.get_collection_summary_by_id(
             collection_id).contributors_summary
         self.assertEqual(expected, contributors_summary)

diff --git a/core/domain/exp_domain_test.py b/core/domain/exp_domain_test.py
@@ -4256,6 +4256,7 @@ def test_convert_exploration_to_player_dict(self):
         exploration.add_states([second_state_name])
 
         def _get_default_state_dict(content_str, dest_name):
+            """Gets the default state dict of the exploration."""
             return {
                 'classifier_model_id': None,
                 'content': {

diff --git a/core/domain/feedback_services_test.py b/core/domain/feedback_services_test.py
@@ -154,6 +154,9 @@ def setUp(self):
             category='Architecture', language_code='fi')
 
     def _get_all_messages_read(self, user_id, thread_id):
+        """Returns the list of the ids of all the messages corresponding to the
+        given thread id read by the user.
+        """
         feedback_thread_user_model = (
             feedback_models.GeneralFeedbackThreadUserModel.get(
                 user_id, thread_id))
@@ -163,6 +166,7 @@ def _get_all_messages_read(self, user_id, thread_id):
             feedback_thread_user_model else [])
 
     def _run_computation(self):
+        """Runs the MockFeedbackAnalyticsAggregator computation."""
         MockFeedbackAnalyticsAggregator.start_computation()
         self.assertEqual(
             self.count_jobs_in_taskqueue(
@@ -256,6 +260,9 @@ def test_get_total_open_threads_for_multiple_explorations(self):
         self.assertEqual(1, len(threads_exp_2))
 
         def _close_thread(thread_id):
+            """Closes the thread corresponding to its thread id by updating its
+            status.
+            """
             thread = feedback_models.GeneralFeedbackThreadModel.get_by_id(
                 thread_id)
             thread.status = feedback_models.STATUS_CHOICES_FIXED

diff --git a/core/domain/interaction_registry.py b/core/domain/interaction_registry.py
@@ -39,6 +39,9 @@ def get_all_interaction_ids(cls):
 
     @classmethod
     def _refresh(cls):
+        """Refreshes and updates all the interaction ids to add new interaction
+        instances to the registry.
+        """
         cls._interactions.clear()
 
         all_interaction_ids = cls.get_all_interaction_ids()

diff --git a/core/domain/rte_component_registry_test.py b/core/domain/rte_component_registry_test.py
@@ -46,7 +46,7 @@
 
 
 class RteComponentUnitTests(test_utils.GenericTestBase):
-    """Tests that all the default RTE comopnents are valid."""
+    """Tests that all the default RTE components are valid."""
 
     def _is_camel_cased(self, name):
         """Check whether a name is in CamelCase."""
@@ -57,6 +57,7 @@ def _is_alphanumeric_string(self, input_string):
         return bool(re.compile('^[a-zA-Z0-9_]+$').match(input_string))
 
     def _validate_customization_arg_specs(self, customization_arg_specs):
+        """Validates the given customization arg specs."""
         for ca_spec in customization_arg_specs:
             self.assertEqual(set(ca_spec.keys()), set([
                 'name', 'description', 'schema', 'default_value']))

diff --git a/core/domain/stats_domain_test.py b/core/domain/stats_domain_test.py
@@ -27,6 +27,9 @@ class ExplorationStatsTests(test_utils.GenericTestBase):
     """Tests the ExplorationStats domain object."""
 
     def _get_exploration_stats_from_dict(self, exploration_stats_dict):
+        """Converts and returns the ExplorationStats object from the given
+        exploration stats dict.
+        """
         state_stats_mapping = {}
         for state_name in exploration_stats_dict['state_stats_mapping']:
             state_stats_mapping[state_name] = stats_domain.StateStats.from_dict(

diff --git a/core/domain/story_services.py b/core/domain/story_services.py
@@ -653,6 +653,15 @@ def publish_story(story_id, committer_id):
         Exception. The user does not have enough rights to publish the story.
     """
     def _are_nodes_valid_for_publishing(story_nodes):
+        """Validates the story nodes before publishing.
+
+        Args:
+            story_nodes: list(dict(str, *)). The list of story nodes dicts.
+
+        Raises:
+            Exception: The story node doesn't contain any exploration id or the
+                exploration id is invalid or isn't published yet.
+        """
         exploration_id_list = []
         for node in story_nodes:
             if not node.exploration_id:

diff --git a/core/domain/user_jobs_continuous_test.py b/core/domain/user_jobs_continuous_test.py
@@ -92,6 +92,7 @@ class RecentUpdatesAggregatorUnitTests(test_utils.GenericTestBase):
     def _get_expected_activity_created_dict(
             self, user_id, activity_id, activity_title, activity_type,
             commit_type, last_updated_ms):
+        """Returns the dict containing expected activity details."""
         return {
             'activity_id': activity_id,
             'activity_title': activity_title,
@@ -104,18 +105,27 @@ def _get_expected_activity_created_dict(
         }
 
     def _get_most_recent_exp_snapshot_created_on_ms(self, exp_id):
+        """Returns the most recent snapshot of the exploration corresponding to
+        the given exploration id.
+        """
         most_recent_snapshot = exp_services.get_exploration_snapshots_metadata(
             exp_id)[-1]
         return most_recent_snapshot['created_on_ms']
 
     def _get_most_recent_collection_snapshot_created_on_ms(
             self, collection_id):
+        """Returns the most recent snapshot of the collection corresponding to
+        the given collection id.
+        """
         most_recent_snapshot = (
             collection_services.get_collection_snapshots_metadata(
                 collection_id)[-1])
         return most_recent_snapshot['created_on_ms']
 
     def _get_test_context(self):
+        """Swaps ALL_CONTINUOUS_COMPUTATION_MANAGERS with
+        ALL_CC_MANAGERS_FOR_TESTS in jobs registry.
+        """
         return self.swap(
             jobs_registry, 'ALL_CONTINUOUS_COMPUTATION_MANAGERS',
             self.ALL_CC_MANAGERS_FOR_TESTS)
@@ -660,6 +670,9 @@ def _generate_user_ids(self, count):
         return ['user%d' % i for i in range(count)]
 
     def _create_exploration(self, exp_id, user_id):
+        """Creates the default exploration with the given exploration id and
+        then, returns its instance.
+        """
         exploration = exp_domain.Exploration.create_default_exploration(exp_id)
         exp_services.save_new_exploration(user_id, exploration)
         return exploration
@@ -685,6 +698,9 @@ def _rate_exploration(self, exp_id, num_ratings, rating):
                 user_id, exp_id, rating)
 
     def _record_exploration_rating(self, exp_id, ratings):
+        """Records the exploration rating corresponding to the given exploration
+        id.
+        """
         user_ids = self._generate_user_ids(len(ratings))
         self.process_and_flush_pending_tasks()
         for ind, user_id in enumerate(user_ids):
@@ -694,6 +710,9 @@ def _record_exploration_rating(self, exp_id, ratings):
 
     def _record_exploration_rating_for_user(
             self, exp_id, user_id, rating, old_rating=None):
+        """Records the exploration rating provided by the user corresponding to
+        the given user id.
+        """
         self.process_and_flush_pending_tasks()
         event_services.RateExplorationEventHandler.record(
             exp_id, user_id, rating, old_rating)