Repository: oppia/oppia

Issue:
Update docstrings in the Python backend code to follow the style guide.
We've been a bit lax about adding docstrings to code in the backend. Instead, we should be following the style guide: https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments -- docstrings should define args, return values, exceptions, etc. The aim of this issue is to ensure that the backend code is properly documented; we will tackle this on a file-by-file basis.

Note: if you're a new contributor, this issue is a particularly good introductory one to tackle, since it will require reading, understanding and documenting the purpose of a file in the codebase, and help you get acquainted with how the Oppia backend is structured. It's important that you're able to communicate and write clearly, though!

Some useful tips:
-  Please follow our [style guide](https://github.com/oppia/oppia/wiki/Coding-style-guide#general) (and also the [Google Python style guide](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments)) when writing docstrings. Make sure to follow the patterns established there as closely as possible, including spacing, capitalization and punctuation. Also, it's a good idea to look at some of the existing files (see below) to get a sense of the correct format -- we recommend following this closely in order to maintain uniformity across the codebase.
- If applicable, make sure that the docstrings for all functions correctly specify the args, return values, etc. If a function has no args, you can omit the Args section; if it has no return value, you can omit the Returns section.
- If a docstring is not present in the code, or the existing one is too vague for you to understand what's going on just by looking at it, then it should be rewritten to be more clear. You'll often need to read the code as well, and do a grep on the callsites to see how it's being used, in order to get a clear understanding of what it's doing. This is good practice for learning how to navigate the codebase, and is an intended part of this project.
- If you feel that parts of the codebase are unclear or incorrectly factored, please feel free to bring this up! The whole point of docstrings is to improve code health and accessibility for new developers, so if you spot other things that can be done in service of that aim, we should also look into doing that.

**Completed:**
- [x] core.controllers.base @shaz13 
- [x] core.controllers.cron @saeedjassani
- [x] core.controllers.reader @96mohitm
- [x] core.domain.activity_domain @andromfins
- [x] core.domain.activity_services @souravsingh
- [x] core.domain.classifier_services @andromfins 
- [x] core.domain.collection_domain @domevit
- [x] core.domain.collection_services @kahkhang 
- [x] core.domain.config_services @vibhor98 
- [x] core.domain.email_manager @Oishikatta 
- [x] core.domain.exp_domain @domevit
- [x] core.domain.exp_services @DubeySandeep
- [x] core.domain.feedback_domain @terrameijar 
- [x] core.domain.feedback_jobs_continuous
- [x] core.domain.feedback_services @andimeo
- [x] core.domain.fs_domain @kartik-25 
- [x] core.domain.html_cleaner @seanlip
- [x] core.domain.param_domain @rohan-gulati
- [x] core.domain.rating_services @BojOnTheBeat 
- [x] core.domain.rights_manager @ayejay
- [x] core.domain.stats_domain @Arunabh98
- [x] core.domain.stats_jobs_continuous @Arunabh98 
- [x] core.domain.stats_jobs_one_off @zpuller
- [x] core.domain.stats_services @manoj-makkuboy 
- [x] core.domain.subscription_services @vibhor98 
- [x] core.domain.summary_services @domevit 
- [x] core.domain.user_jobs_continuous @shubha1593 
- [x] core.domain.user_services @Nalinc 
- [x] core.domain.value_generators_domain @meetsha 
- [x] core.jobs @brianrodri
- [x] core.platform.app_identity.gae_app_identity_services @ubhisat
- [x] core.platform.models @pranavsid98 
- [x] core.platform.transactions.gae_transaction_services @ubhisat
- [x] core.storage.base_model.gae_models @vojtechjelinek
- [x] core.storage.collection.gae_models @kaggis
- [x] core.storage.email.gae_models @rajan-garg
- [x] core.storage.exploration.gae_models @kirankonduru
- [x] core.storage.feedback.gae_models @naveenshukla
- [x] core.storage.file.gae_models @Ian91 
- [x] core.storage.job.gae_models @sasacocic
- [x] core.storage.statistics.gae_models @abhishekarya286
- [x] core.storage.user.gae_models @Anthony-Alridge 
- [x] core.tests.test_util_jobs @seanlip
- [x] core.tests.test_utils @vibhor98
- [x] utils @yashLadha 


Discussion:
@seanlip I would like to work in the issue.

Hi @souravsingh, do you think you could finish up #2051 first, please? Thanks! 

@seanlip I would like to work on this issue.


Resolving patch:
diff --git a/core/domain/activity_services.py b/core/domain/activity_services.py
--- a/core/domain/activity_services.py
+++ b/core/domain/activity_services.py
@@ -25,6 +25,12 @@
 
 
 def get_featured_activity_references():
+    """Gets a list of ActivityReference domain models.
+
+    Returns:
+        A list of all ActivityReference domain objects that are
+        currently featured.
+    """
     featured_model_instance = (
         activity_models.ActivityReferencesModel.get_or_create(
             activity_models.ACTIVITY_REFERENCE_LIST_FEATURED))
@@ -37,8 +43,13 @@ def get_featured_activity_references():
 def update_featured_activity_references(featured_activity_references):
     """Updates the current list of featured activity references.
 
-    This assumes that the input is a list of activity references corresponding
-    to publicly-viewable activities.
+    Args:
+        featured_activity_references: A list of ActivityReference domain
+            objects representing the full list of 'featured' activities.
+
+    Raises:
+         Exception: The input list of ActivityReference
+            domain objects has duplicates.
     """
     for activity_reference in featured_activity_references:
         activity_reference.validate()
@@ -58,6 +69,13 @@ def update_featured_activity_references(featured_activity_references):
 
 
 def remove_featured_activity(activity_type, activity_id):
+    """Removes the specified activity reference from the
+        list of featured activity references.
+
+    Args:
+        activity_type: str. The type of the activity to remove.
+        activity_id: str. The id of the activity to remove.
+    """
     featured_references = get_featured_activity_references()
 
     activity_reference_found = False
@@ -83,8 +101,16 @@ def split_by_type(activity_references):
     The elements in each of the returned lists are in the same order as those
     in the input list.
 
-    If any activity reference is incorrectly formatted, this raises an
-    Exception.
+    Args:
+        activity_references: A list of ActivityReference domain objects.
+
+    Returns:
+        A 2-tuple whose first element is a list of all exploration
+        ids represented in the input list, and whose second element
+        is a list of all collection ids represented in the input list.
+
+    Raises:
+        Exception: The activity reference type is invalid.
     """
     exploration_ids, collection_ids = [], []
     for activity_reference in activity_references:


Test patch: