oppia: [Incomplete] Adding/Updating 'Args', 'Raises', and 'Return' in docstrings

Aim/Problem: Improve the docstrings in all the python files in the codebase. This will also fulfill the prerequisite for the lint check Check to enforce use of Args, Returns and Raises in the docstring. to be introduced for #8423.

Suggested fix: Do a grep or a search (CTRL+F) for def keyword in the file to get all the possible places (i.e functions and methods) that we would need to fix. Verify that the correct pattern for docstring (which includes Args, Return, and Raises if applicable as shown below) exists for all those functions/methods, and if it is not already present, then edit their doc string. An example of a good docstring is shown below:

def someFunction(param1, param2):
    """This is a sample of a correct docstring.
    Args:
         param1: <type>. <details>.
         param2: <type>. <details>.
         
    Returns:
        <type>. <details>.

    Raises:
        <error_type>. <details>.
    """
    # <rest of the function >

where, Args denotes all parameters with its type and details, Raises denotes all the types of errors/exceptions that could be raised, and Returns denotes the details about what a function returns.

Important: Docstrings are not required for test and setUp functions in the test files(files that end with _test.py).

To be assigned one of the below tasks, leave a comment at-mentioning @SD-13 and specify which one you want to take up.

The list of files that need improvement (Please create a PR that fixes all the files assigned under one checkbox):

oppia @aasiffaizal (#12287)
- oppia.utils
- oppia.constants
- oppia.appengine_config
- oppia.schema_utils_test
- oppia.utils_test
- oppia.python_utils
oppia.core (assigned 2023-03-15) @deadex-ng(#18216)
- oppia.core.jobs_test
- oppia.core.jobs
- oppia.core.platform_feature_list_test
oppia.core.controllers : PART 1 (assigned 2023-04-25) @Helper2020
- oppia.core.controllers.custom_landing_pages
- oppia.core.controllers.subtopic_viewer
- oppia.core.controllers.concept_card_viewer
- oppia.core.controllers.suggestion
- oppia.core.controllers.topics_and_skills_dashboard
- oppia.core.controllers.admin_test
- oppia.core.controllers.topic_viewer
- oppia.core.controllers.editor
- oppia.core.controllers.contributor_dashboard
- oppia.core.controllers.story_viewer
oppia.core.controllers : PART 2 (assigned 2023-07-13) @shubham-kshetre
- oppia.core.controllers.creator_dashboard_test
- oppia.core.controllers.feedback_test
- oppia.core.controllers.practice_sessions
- oppia.core.controllers.cron_test
- oppia.core.controllers.classroom
- oppia.core.controllers.topic_editor
- oppia.core.controllers.profile
- oppia.core.controllers.question_editor
- oppia.core.controllers.classifier
- oppia.core.controllers.voice_artist
oppia.core.controllers : PART 3
- oppia.core.controllers.tasks_test
- oppia.core.controllers.questions_list
- oppia.core.controllers.story_viewer_test
- oppia.core.controllers.collection_viewer
- oppia.core.controllers.resources
- oppia.core.controllers.classifier_test
- oppia.core.controllers.review_tests
- oppia.core.controllers.profile_test
- oppia.core.controllers.editor_test
- oppia.core.controllers.features_test
oppia.core.controllers : PART 4
- oppia.core.controllers.learner_dashboard
- oppia.core.controllers.resources_test
- oppia.core.controllers.skill_editor
- oppia.core.controllers.base
- oppia.core.controllers.story_editor
- oppia.core.controllers.reader_test
- oppia.core.controllers.collection_editor
- oppia.core.controllers.platform_feature_test
oppia.core.controllers : PART 5 @deadex-ng
- oppia.core.controllers.acl_decorators_test
- oppia.core.controllers.acl_decorators
- oppia.core.controllers.email_dashboard
- oppia.core.controllers.question_editor_test
- oppia.core.controllers.skill_editor_test
- oppia.core.controllers.library_test
- oppia.core.controllers.reader
oppia.core.storage : PART 1
- oppia.core.storage.classifier.gae_models
- oppia.core.storage.recommendations.gae_models
- oppia.core.storage.audit.gae_models
- oppia.core.storage.subtopic.gae_models
- oppia.core.storage.suggestion.gae_models
- oppia.core.storage.email.gae_models
- oppia.core.storage.email.gae_models_test
- oppia.core.storage.config.gae_models
- oppia.core.storage.auth.gae_models
oppia.core.storage : PART 2
- oppia.core.storage.story.gae_models
- oppia.core.storage.statistics.gae_models
- oppia.core.storage.statistics.gae_models_test
- oppia.core.storage.topic.gae_models
- oppia.core.storage.feedback.gae_models
- oppia.core.storage.exploration.gae_models
- oppia.core.storage.improvements.gae_models
- oppia.core.storage.improvements.gae_models_test
- oppia.core.storage.skill.gae_models
oppia.core.storage : PART 3
- oppia.core.storage.activity.gae_models
- oppia.core.storage.collection.gae_models
- oppia.core.storage.question.gae_models
- oppia.core.storage.question.gae_models_test
- oppia.core.storage.opportunity.gae_models
- oppia.core.storage.job.gae_models
- oppia.core.storage.base_model.gae_models
- oppia.core.storage.user.gae_models
oppia.core.tests (assigned 2023-03-14) @deadex-ng #17727
- oppia.core.tests.test_utils_test
- oppia.core.tests.gae_suite
- oppia.core.tests.test_utils
- oppia.core.tests.gae_suite_test
oppia.core.platform
- oppia.core.platform.models_test
- oppia.core.platform.app_identity.gae_app_identity_services
- oppia.core.platform.search.elastic_search_services_test
- oppia.core.platform.search.gae_search_services
- oppia.core.platform.search.gae_search_services_test
- oppia.core.platform.datastore.gae_datastore_services
- oppia.core.platform.email.mailgun_email_services_test
- oppia.core.platform.email.dev_mode_email_services_test
- oppia.core.platform.auth.firebase_auth_services_test
- oppia.core.platform.taskqueue.cloud_taskqueue_services_test
- oppia.core.platform.transactions.gae_transaction_services
oppia.core.domain : PART 1 @amaanlari
- oppia.core.domain.skill_validators
- oppia.core.domain.feedback_jobs_one_off_test
- oppia.core.domain.collection_services_test
- oppia.core.domain.skill_jobs_one_off
- oppia.core.domain.job_validators
- oppia.core.domain.exp_jobs_one_off
- oppia.core.domain.opportunity_validators
- oppia.core.domain.recommendations_jobs_one_off
- oppia.core.domain.recommendations_services
- oppia.core.domain.statistics_validators_test
oppia.core.domain : PART 2
- oppia.core.domain.stats_jobs_one_off_test
- oppia.core.domain.collection_domain
- oppia.core.domain.config_domain
- oppia.core.domain.question_validators
- oppia.core.domain.cron_services
- oppia.core.domain.value_generators_domain
- oppia.core.domain.classifier_validators
- oppia.core.domain.suggestion_services_test
- oppia.core.domain.rating_services
- oppia.core.domain.config_validators
oppia.core.domain : PART 3
- oppia.core.domain.suggestion_validators
- oppia.core.domain.topic_jobs_one_off_test
- oppia.core.domain.user_query_jobs_one_off_test
- oppia.core.domain.activity_jobs_one_off_test
- oppia.core.domain.event_services
- oppia.core.domain.activity_services_test
- oppia.core.domain.skill_jobs_one_off_test
- oppia.core.domain.user_jobs_continuous
- oppia.core.domain.platform_parameter_domain_test
oppia.core.domain : PART 4
- oppia.core.domain.classifier_services_test
- oppia.core.domain.opportunity_jobs_one_off
- oppia.core.domain.question_domain
- oppia.core.domain.collection_jobs_one_off
- oppia.core.domain.auth_validators
- oppia.core.domain.email_domain
- oppia.core.domain.feedback_jobs_continuous_test
- oppia.core.domain.email_manager_test
- oppia.core.domain.feedback_jobs_one_off
- oppia.core.domain.rights_domain
oppia.core.domain : PART 5
- oppia.core.domain.topic_validators
- oppia.core.domain.recommendations_jobs_one_off_test
- oppia.core.domain.topic_services_test
- oppia.core.domain.base_model_validators_test
- oppia.core.domain.activity_domain
- oppia.core.domain.fs_domain
- oppia.core.domain.email_validators
- oppia.core.domain.interaction_jobs_one_off
- oppia.core.domain.rte_component_registry
- oppia.core.domain.user_domain
oppia.core.domain : PART 6
- oppia.core.domain.skill_services_test
- oppia.core.domain.stats_domain
- oppia.core.domain.activity_validators
- oppia.core.domain.story_jobs_one_off
- oppia.core.domain.suggestion_validators_test
- oppia.core.domain.question_jobs_one_off
- oppia.core.domain.story_domain
- oppia.core.domain.story_validators
- oppia.core.domain.stats_domain_test
- oppia.core.domain.state_domain
oppia.core.domain : PART 7
- oppia.core.domain.stats_jobs_continuous
- oppia.core.domain.story_jobs_one_off_test
- oppia.core.domain.question_services
- oppia.core.domain.obj_services
- oppia.core.domain.param_domain
- oppia.core.domain.statistics_validators
- oppia.core.domain.classifier_domain_test
- oppia.core.domain.platform_parameter_registry_test
- oppia.core.domain.user_validators
- oppia.core.domain.interaction_registry
oppia.core.domain : PART 8
- oppia.core.domain.skill_services
- oppia.core.domain.topic_jobs_one_off
- oppia.core.domain.rte_component_registry_test
- oppia.core.domain.rights_domain_test
- oppia.core.domain.exp_services
- oppia.core.domain.collection_domain_test
- oppia.core.domain.feedback_domain
- oppia.core.domain.classifier_domain
- oppia.core.domain.stats_jobs_continuous_test
- oppia.core.domain.recommendations_validators
oppia.core.domain : PART 9
- oppia.core.domain.user_jobs_one_off_test
- oppia.core.domain.exp_domain_test
- oppia.core.domain.email_jobs_one_off
- oppia.core.domain.email_validators_test
- oppia.core.domain.question_services_test
- oppia.core.domain.audit_validators
- oppia.core.domain.learner_progress_services_test
- oppia.core.domain.search_services_test
- oppia.core.domain.suggestion_registry
- oppia.core.domain.topic_domain_test
oppia.core.domain : PART 10
- oppia.core.domain.user_domain_test
- oppia.core.domain.user_query_jobs_one_off
- oppia.core.domain.learner_playlist_services_test
- oppia.core.domain.platform_parameter_domain
- oppia.core.domain.suggestion_jobs_one_off_test
- oppia.core.domain.subtopic_page_domain_test
- oppia.core.domain.exp_services_test
- oppia.core.domain.question_domain_test
- oppia.core.domain.story_services_test
- oppia.core.domain.opportunity_services
oppia.core.domain : PART 11
- oppia.core.domain.prod_validation_jobs_one_off
- oppia.core.domain.auth_domain
- oppia.core.domain.suggestion_jobs_one_off
- oppia.core.domain.user_services_test
- oppia.core.domain.wipeout_jobs_one_off
- oppia.core.domain.image_validation_services_test
- oppia.core.domain.prod_validators
- oppia.core.domain.html_validation_service_test
- oppia.core.domain.feedback_services_test
- oppia.core.domain.visualization_registry
oppia.core.domain : PART 12
- oppia.core.domain.stats_services_test
- oppia.core.domain.story_domain_test
- oppia.core.domain.user_jobs_one_off
- oppia.core.domain.skill_domain_test
- oppia.core.domain.calculation_registry
- oppia.core.domain.collection_validators
- oppia.core.domain.activity_jobs_one_off
- oppia.core.domain.feedback_validators
- oppia.core.domain.email_manager
- oppia.core.domain.state_domain_test
oppia.core.domain : PART 13
- oppia.core.domain.opportunity_services_test
- oppia.core.domain.interaction_jobs_one_off_test
- oppia.core.domain.rating_services_test
- oppia.core.domain.improvements_validators
- oppia.core.domain.topic_domain
- oppia.core.domain.wipeout_jobs_one_off_test
- oppia.core.domain.user_jobs_continuous_test
- oppia.core.domain.moderator_services
- oppia.core.domain.role_services
- oppia.core.domain.stats_jobs_one_off
- oppia.core.domain.base_model_validators
- oppia.core.domain.exp_jobs_one_off_test
oppia.extensions
- oppia.extensions.domain
- oppia.extensions.rich_text_components.components
- oppia.extensions.visualizations.models
- oppia.extensions.value_generators.models.generators
- oppia.extensions.actions.base
- oppia.extensions.issues.base
- oppia.extensions.interactions.base
- oppia.extensions.interactions.base_test
- oppia.extensions.answer_summarizers.models_test
- oppia.extensions.answer_summarizers.models
oppia.scripts : PART 1
- oppia.scripts.setup_gae
- oppia.scripts.pre_commit_hook
- oppia.scripts.docstrings_checker
- oppia.scripts.common
- oppia.scripts.typescript_checks_test
- oppia.scripts.concurrent_task_utils_test
- oppia.scripts.setup_test
- oppia.scripts.docstrings_checker_test
- oppia.scripts.install_third_party_test
- oppia.scripts.pre_commit_hook_test
oppia.scripts : PART 2
- oppia.scripts.check_frontend_coverage_test
- oppia.scripts.run_lighthouse_tests
- oppia.scripts.common_test
- oppia.scripts.build
- oppia.scripts.run_frontend_tests
- oppia.scripts.build_test
- oppia.scripts.run_e2e_tests
- oppia.scripts.setup_gae_test
- oppia.scripts.concurrent_task_utils
- oppia.scripts.run_tests
oppia.scripts : PART 3
- oppia.scripts.typescript_checks
- oppia.scripts.run_e2e_tests_test
- oppia.scripts.run_portserver
- oppia.scripts.create_expression_parser
- oppia.scripts.script_import_test
- oppia.scripts.install_backend_python_libs_test
- oppia.scripts.run_presubmit_checks
- oppia.scripts.install_third_party
- oppia.scripts.start
- oppia.scripts.pre_push_hook
oppia.scripts : PART 4
- oppia.scripts.run_backend_tests
- oppia.scripts.install_third_party_libs
- oppia.scripts.setup
- oppia.scripts.flake_checker_test
- oppia.scripts.clean_test
- oppia.scripts.pre_push_hook_test
- oppia.scripts.flake_checker
- oppia.scripts.install_third_party_libs_test
- oppia.scripts.check_e2e_tests_are_captured_in_ci_test
- oppia.scripts.clean
oppia.scripts.release_scripts
- oppia.scripts.release_scripts.cut_release_or_hotfix_branch_test
- oppia.scripts.release_scripts.update_changelog_and_credits_test
- oppia.scripts.release_scripts.cut_release_or_hotfix_branch
- oppia.scripts.release_scripts.repo_specific_changes_fetcher_test
- oppia.scripts.release_scripts.update_configs_test
oppia.scripts.linters : PART 1
- oppia.scripts.linters.other_files_linter_test
- oppia.scripts.linters.pre_commit_linter_test
- oppia.scripts.linters.linter_utils_test
- oppia.scripts.linters.general_purpose_linter
- oppia.scripts.linters.js_ts_linter
- oppia.scripts.linters.codeowner_linter_test
- oppia.scripts.linters.other_files_linter
oppia.scripts.linters : PART 2
- oppia.scripts.linters.python_linter
- oppia.scripts.linters.html_linter
- oppia.scripts.linters.js_ts_linter_test
- oppia.scripts.linters.css_linter_test
- oppia.scripts.linters.css_linter
- oppia.scripts.linters.linter_utils
- oppia.scripts.linters.general_purpose_linter_test
- oppia.scripts.linters.pre_commit_linter

About this issue

Original URL
State: open
Created 3 years ago
Comments: 102 (72 by maintainers)

Commits related to this issue

Fix part of #11776. Adding/Updating 'Args' and 'Return' in docstrings (#12287) * Added/updated args, return and raises in docstring * Fixed lint issues * Removed unwanted Raises * Update pyt... — committed to oppia/oppia by aasiffaizal 3 years ago
Fix part of #11776. Adding/Updating 'Args' and 'Return' in docstrings (#17727) * Adding/Updating Args, Raises, and Return in docstrings * Adding/Updating Args, Raises, and Return in docstrings * Ad... — committed to oppia/oppia by deadex-ng a year ago
Fix part of #11776. Adding/Updating 'Args' and 'Return' in docstrings (#18216) * Added/updated args, return and raises in docstring * Added/updated args, return and raises in docstring * fix pylint... — committed to oppia/oppia by deadex-ng a year ago
Fix part of #11776. Adding/Updating 'Args' and 'Return' in docstrings (#18712) * Add or edited docstrings in contributor_dashboard.py * Added or edited docstrings in story_viewer.py * Added or edit... — committed to oppia/oppia by Helper2020 9 months ago
Merge pull request #2 from shubham-kshetre/dockstrings Fix part of #11776: Adding/Updating 'Args' and 'Return' in docstrings for oppia.core.controllers.creator_dashboard_test — committed to shubham-kshetre/oppia by shubham-kshetre 6 months ago

Most upvoted comments

@KartikKapil This might happen if you don’t start with a description and straightaway start with Args. Try adding a description then blank line, then Args and so on.

hardikkat24 on Mar 20, 2021

@nikitaevg Just a note – I haven’t forgotten about this comment. I’m planning to talk with Ben about this as well but haven’t had a chance to meet him yet; will come back to it.

seanlip on Jan 10, 2024

@seanlip Absolutely, I’m up for the challenge! I’ll dive into the lint checks documentation and work on building the detection as per the requirements. If I encounter any roadblocks, I’ll make sure to create a debugging doc and reach out for assistance. Thanks for entrusting me with this task!

EDIT (by @seanlip): See https://github.com/oppia/oppia/discussions/19337#discussioncomment-8266975 for follow-up conversation.

amaanlari on Jan 27, 2024

@SD-13 Okay sure

amaanlari on Nov 5, 2023

Yes, all methods should have descriptions, and only applicable methods would have Args/Raises/Returns sections in their docstring.

seanlip on Jul 15, 2023

@shubham-kshetre go ahead, assigned to you.

SD-13 on Jul 13, 2023

Also, @Helper2020, I just realized this is a general issue thread. Let’s perhaps have this conversation on your PR thread instead, rather than here.

seanlip on Jul 11, 2023

@Helper2020 That function is wrong, it should be like the other handlers where there’s no return at the end. Feel free to fix that as part of your PR.

seanlip on Jun 20, 2023

@Helper2020 Yes there is, did you see our linter wiki pages? https://github.com/oppia/oppia/wiki/Lint-Checks#run-linters

seanlip on Jun 2, 2023

Hi @Helper2020, if we don’t use *args then can we remove it from the argument list in the code as well? That will help keep everything consistent.

seanlip on May 16, 2023

@deadex-ng, are you still working on oppia.core?

@SD-13 I just opened a PR on that.

deadex-ng on May 11, 2023

@U8NWXD Hello can I work oppia.core.controllers : PART 1 ?

Helper2020 on Apr 17, 2023

Can I work on oppia.core?

deadex-ng on Mar 15, 2023

@U8NWXD Can I work on oppia.core.tests?

deadex-ng on Mar 12, 2023

@sajalasati @hardikkat24 My changes are merged #12287, can you update the description?

Done!

sajalasati on Mar 30, 2021

@Nisarg-Chaudhari I have assigned you.

hardikkat24 on Mar 22, 2021

@KartikKapil You might have added get-pip.py file to get pip installed on your system. Please delete that file or move it to some other directory. This should solve the problem.

hardikkat24 on Mar 21, 2021

@sajalasati could i ping you gitter? Regarding this issue

@KartikKapil I am not sure if I can be available much on gitter. You can use this thread to ask all your doubts without any worry, and we will try to clear them or guide you to proper resources/wiki pages (it will only help future contributors working on this issue to get things cleared early on). If you have setup related questions you can use oppia-chat on gitter. We encourage usage of public chats more than DMs 😃

sajalasati on Mar 18, 2021

@sajalasati i have a query, while making the doc string if a fuction returns a list which contains a model should i write it returns a list or should i also write what the returning model does ?

@KartikKapil You can look at other examples in the file to get an idea - generally we write it in the docstring as Returns: list(<data_type>) (link) where data type could also be the name of a model.

sajalasati on Mar 17, 2021

Ok, I will start with 3rd. !

@Siddhant-K-code Assigned you to 3rd checkbox - oppia.core.controllers. Do Let us know if you have any questions!

sajalasati on Mar 17, 2021

Yes, I would like to work on this, I can work on whole files ( except 1st and 2nd {already Assigned } ). Please Assign me, @sajalasati

@Siddhant-K-code There are approx 280+ files remaining, and if you cover it in a single PR it will become very large and will take long time to review. I would advice taking individual checkboxes for now, or I am even fine if you want to pick one entire folder at a time like oppia.core.controllers (which has 5 parts/checkboxes) or oppia.core.domain (10 parts). Let me know, and I will assign you. (I can assign you more in future as you start making PRs)

sajalasati on Mar 17, 2021

@sajalasati Could i work on the second check box (i.e oppia.core)

@KartikKapil I’ve assigned you 😃

sajalasati on Mar 16, 2021

Can I try to fix this?

@Siddhant-K-code Sorry for delayed response. Actually no one was assigned to this issue earlier. If you are still interested to work on it, can you pick one task (checkbox) and I will assign it to you. (I have also updated the issue description, so kindly go through that once more to understand the task). Thanks!

sajalasati on Mar 13, 2021