Lightrun
question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

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

See original GitHub issue

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.

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

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 @KartikKapil
    • oppia.core.jobs_test
    • oppia.core.jobs
    • oppia.core.platform_feature_list_test
  • oppia.core.controllers : PART 1 @Siddhant-K-code
    • 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
    • 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
    • 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
    • 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
    • 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

Issue Analytics

  • State:open
  • Created 3 years ago
  • Comments:51 (30 by maintainers)

github_iconTop GitHub Comments

2reactions
hardikkat24commented, Mar 20, 2021

@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.

1reaction
sajalasaticommented, Mar 30, 2021

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

Done!

Read more comments on GitHub >

github_iconTop Results From Across the Web

Python Docstring: raise vs. raises
raises is used to describe the possible exceptions being raised. raise is recognized by Sphinx when running autodoc and is the same as...
Read more >
Python Docstrings Tutorial : Examples & Format for Pydoc ...
Help on function string_reverse in module __main__: string_reverse(str1) Returns the reversed String. Parameters: str1 (str):The string which is to be reversed.
Read more >
Example Google Style Python Docstrings - Napoleon
If attribute, parameter, and return types are annotated according to `PEP 484`_, they do not need to be included in the docstring: Args:...
Read more >
Comments, Docstrings, and Type Hints in Python Code
In the following, we will see how we should properly use comments, docstrings, and type hints to make our code easier to understand....
Read more >
2. Example on how to document your Python docstrings
Just looking at the docstring, the parameter, type and return sections do not appear nicely. Parameters: arg1 (int, float,...) – the first value;...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found
Previous page

Unexpected lint error when using "bypass" in a comment

Next page

Write Lint Checks for the End-to-End Tests