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.

Update docstrings in the python backend code.

See original GitHub issue

The aim of this issue is to ensure that every backend file is properly documented. The docstrings serve as guidance to developers to help them understand what a class or a method is doing, so they must be written accurately.

Some useful tips:

Please follow our style guide and also the Google Python style guide when writing the docstrings. Make sure to follow the patterns established there as closely as possible, including spacing, capitalization and punctuation.
Make sure that the docstrings for every function include Args, Returns, Raises etc. as and when applicable. If there are no args, then you can omit writing Args. Likewise for Returns, Raises etc. as well.
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 to find out specific method used in several files and in many other situations.
Every argument name under Args and under Returns or Raises should have a data type mentioned along with it. Make separate efforts to analyze their data types as this might be a bit tricky sometimes and there are many chances of getting mistaken. You can, for example, try to run the method/function while temporarily adding raise(type(X)) or logging.info(type(X)) to get the information you need.
Leave one line before each of Args, Returns and Raises. Indent any continuation lines by 4 spaces. See existing docstrings for examples.
If you feel that some files are absent from the list or some parts of the codebase are unclear or incorrectly factored, please feel free to bring this up!

Running tests on a specific file

Go to the directory where the file is present (say-- if the file is in core directory, perform cd core to reach to the directory).
Execute pylint --disable=all --enable=missing-docstring <filename> to perform linter checks on the file. (Note: If you face any problem while running the above command, please comment out this line in .pylintrc locally and uncomment it when pushing your changes).
Add docstrings for the lines where you find ‘Missing docstrings’.

Here is the list of files that are required to be updated. Note: Once this issue is complete, we will turn on missing-docstring checks in Oppia’s Python linter. Also, take care that some of the test methods/classes have to be excluded from the test files as they don’t require docstrings in detail.

Docstrings for test methods (test_* type) and test classes (*Tests type) don’t need docstrings and hence, can be excluded while adding docstrings to the test files. Please add no-docstring-rgx=test_[a-z_]*|[a-zA-Z]*Tests|Test[a-zA-Z]* regex in .pylintrc file under [Basic] section.

Needs to be done (based on code snapshot at 1 Dec 2018):

core.jobs_test @vibhor98 C:497, 4: Missing method docstring (missing-docstring) C:791, 8: Missing function docstring (missing-docstring)
core.jobs @YashJipkate C:103, 4: Missing method docstring (missing-docstring) C:122, 8: Missing function docstring (missing-docstring) C:486, 4: Missing method docstring (missing-docstring) C:490, 4: Missing method docstring (missing-docstring) C:494, 4: Missing method docstring (missing-docstring) C:498, 4: Missing method docstring (missing-docstring) C:502, 4: Missing method docstring (missing-docstring) C:506, 4: Missing method docstring (missing-docstring) C:510, 4: Missing method docstring (missing-docstring) C:514, 4: Missing method docstring (missing-docstring) C:1239, 8: Missing function docstring (missing-docstring) C:1291, 8: Missing function docstring (missing-docstring) C:1471, 8: Missing function docstring (missing-docstring)
core.controllers.skill_editor_test @vibhor98 C: 52, 4: Missing method docstring (missing-docstring) C: 60, 4: Missing method docstring (missing-docstring) C: 66, 4: Missing method docstring (missing-docstring) C: 71, 4: Missing method docstring (missing-docstring) C: 74, 4: Missing method docstring (missing-docstring)
core.controllers.creator_dashboard_test @vibhor98 C:124, 4: Missing method docstring (missing-docstring)
core.controllers.editor_test @vibhor98 C:183, 8: Missing function docstring (missing-docstring) C:195, 8: Missing function docstring (missing-docstring) C:1776, 4: Missing method docstring (missing-docstring) C:1784, 4: Missing method docstring (missing-docstring)
core.controllers.reader_test @vibhor98 C:492, 4: Missing method docstring (missing-docstring) C:495, 4: Missing method docstring (missing-docstring) C:525, 4: Missing method docstring (missing-docstring) C:528, 4: Missing method docstring (missing-docstring) C:532, 4: Missing method docstring (missing-docstring)
core.controllers.resources_test @vibhor98 C: 31, 4: Missing method docstring (missing-docstring)
core.controllers.topics_and_skills_dashboard_test @vibhor98 C: 50, 4: Missing method docstring (missing-docstring)
core.controllers.creator_dashboard @vibhor98 C:168, 8: Missing function docstring (missing-docstring) C:174, 8: Missing function docstring (missing-docstring)
core.controllers.base_test @vibhor98 C:352, 0: Missing class docstring (missing-docstring) C:354, 4: Missing method docstring (missing-docstring) C:360, 4: Missing method docstring (missing-docstring) C:529, 4: Missing class docstring (missing-docstring)
core.controllers.admin @vibhor98 C:198, 4: Missing method docstring (missing-docstring) C:209, 4: Missing method docstring (missing-docstring)
core.controllers.feedback_test @vibhor98 C:396, 4: Missing method docstring (missing-docstring) C:405, 4: Missing method docstring (missing-docstring)
core.platform.users.gae_current_user_services @vibhor98 C: 70, 4: Missing class docstring (missing-docstring)
core.platform.search.gae_search_services @vibhor98 C:100, 0: Missing function docstring (missing-docstring) C:120, 0: Missing function docstring (missing-docstring) C:307, 0: Missing function docstring (missing-docstring) C:340, 0: Missing function docstring (missing-docstring)
core.storage.base_model.gae_models_test @YashJipkate C:124, 0: Missing class docstring (missing-docstring) C:128, 0: Missing class docstring (missing-docstring) C:138, 0: Missing class docstring (missing-docstring)
core.storage.base_model.gae_models @YashJipkate C:423, 4: Missing method docstring (missing-docstring) C:431, 4: Missing method docstring (missing-docstring)
core.storage.user.gae_models @YashJipkate C:178, 4: Missing method docstring (missing-docstring) C:408, 4: Missing method docstring (missing-docstring) C:488, 4: Missing method docstring (missing-docstring)
core.tests.test_utils @YashJipkate C:558, 4: Missing method docstring (missing-docstring)
core.tests.performance_tests.base @YashJipkate C: 47, 4: Missing method docstring (missing-docstring) C: 52, 4: Missing method docstring (missing-docstring) C: 55, 4: Missing method docstring (missing-docstring) C: 58, 4: Missing method docstring (missing-docstring) C: 63, 4: Missing method docstring (missing-docstring) C: 68, 4: Missing method docstring (missing-docstring) C: 80, 4: Missing method docstring (missing-docstring) C: 92, 4: Missing method docstring (missing-docstring) C:114, 4: Missing method docstring (missing-docstring) C:121, 4: Missing method docstring (missing-docstring) C:128, 4: Missing method docstring (missing-docstring) C:135, 4: Missing method docstring (missing-docstring)
core.tests.performance_framework.perf_services @YashJipkate C:208, 4: Missing method docstring (missing-docstring) C:213, 4: Missing method docstring (missing-docstring) C:273, 4: Missing method docstring (missing-docstring) C:278, 4: Missing method docstring (missing-docstring) C:281, 4: Missing method docstring (missing-docstring) C:296, 4: Missing method docstring (missing-docstring) C:308, 4: Missing method docstring (missing-docstring) C:319, 4: Missing method docstring (missing-docstring) C:328, 4: Missing method docstring (missing-docstring) C:336, 4: Missing method docstring (missing-docstring) C:345, 4: Missing method docstring (missing-docstring) C:357, 4: Missing method docstring (missing-docstring) C:360, 4: Missing method docstring (missing-docstring) C:364, 4: Missing method docstring (missing-docstring) C:368, 4: Missing method docstring (missing-docstring) C:372, 4: Missing method docstring (missing-docstring)
core.tests.performance_framework.perf_domain @YashJipkate C:175, 4: Missing method docstring (missing-docstring) C:274, 4: Missing method docstring (missing-docstring)
core.domain.summary_services @YashJipkate C:495, 4: Missing function docstring (missing-docstring)
core.domain.email_jobs_one_off_test @YashJipkate C: 46, 8: Missing function docstring (missing-docstring)
core.domain.visualization_registry @YashJipkate C: 34, 4: Missing method docstring (missing-docstring)
core.domain.feedback_jobs_continuous @vddesai1871 C: 91, 8: Missing function docstring (missing-docstring) C:105, 8: Missing function docstring (missing-docstring) C:119, 8: Missing function docstring (missing-docstring)
core.domain.rte_component_registry_test @vibhor98 C: 59, 4: Missing method docstring (missing-docstring)
core.domain.exp_services_test @dev-ritik C: 50, 0: Missing function docstring (missing-docstring) C:197, 4: Missing method docstring (missing-docstring) C:2463, 8: Missing function docstring (missing-docstring) C:2689, 4: Missing method docstring (missing-docstring)
core.domain.interaction_registry @vibhor98 C: 41, 4: Missing method docstring (missing-docstring)
core.domain.user_jobs_continuous_test @vibhor98 C: 92, 4: Missing method docstring (missing-docstring) C:106, 4: Missing method docstring (missing-docstring) C:111, 4: Missing method docstring (missing-docstring) C:118, 4: Missing method docstring (missing-docstring) C:662, 4: Missing method docstring (missing-docstring) C:687, 4: Missing method docstring (missing-docstring) C:695, 4: Missing method docstring (missing-docstring)
core.domain.calculation_registry @vibhor98 C: 31, 4: Missing method docstring (missing-docstring)
core.domain.classifier_services_test @vibhor98 C: 47, 4: Missing method docstring (missing-docstring)
core.domain.exp_domain_test @vibhor98 C:4258, 8: Missing function docstring (missing-docstring)
core.domain.activity_services_test @vibhor98 C: 36, 4: Missing method docstring (missing-docstring) C: 40, 4: Missing method docstring (missing-docstring) C: 44, 4: Missing method docstring (missing-docstring)
core.domain.feedback_services_test @vibhor98 C:133, 4: Missing method docstring (missing-docstring) C:142, 4: Missing method docstring (missing-docstring) C:236, 8: Missing function docstring (missing-docstring)
core.domain.stats_domain_test @vibhor98 C: 29, 4: Missing method docstring (missing-docstring)
core.domain.story_services @vibhor98 C:655, 4: Missing function docstring (missing-docstring)
core.domain.collection_services_test @vibhor98 C: 41, 0: Missing function docstring (missing-docstring) C:134, 4: Missing method docstring (missing-docstring) C:137, 4: Missing method docstring (missing-docstring) C:336, 4: Missing method docstring (missing-docstring) C:1344, 8: Missing function docstring (missing-docstring) C:1510, 4: Missing method docstring (missing-docstring)
core.domain.user_jobs_one_off_test @vibhor98 C:739, 4: Missing method docstring (missing-docstring) C:742, 4: Missing method docstring (missing-docstring)
core.domain.subscription_services_test @vibhor98 C: 63, 4: Missing method docstring (missing-docstring) C: 70, 4: Missing method docstring (missing-docstring) C: 77, 4: Missing method docstring (missing-docstring) C:363, 4: Missing method docstring (missing-docstring) C:370, 4: Missing method docstring (missing-docstring)
core.domain.obj_services @vibhor98 C: 33, 4: Missing method docstring (missing-docstring)
core.domain.stats_jobs_continuous_test @vibhor98 C: 68, 4: Missing method docstring (missing-docstring) C: 73, 4: Missing method docstring (missing-docstring)
core.domain.user_jobs_continuous @vibhor98 C:389, 8: Missing function docstring (missing-docstring) C:415, 8: Missing function docstring (missing-docstring)
core.domain.feedback_jobs_continuous_test @vibhor98 C: 60, 4: Missing method docstring (missing-docstring) C: 65, 4: Missing method docstring (missing-docstring) C: 73, 4: Missing method docstring (missing-docstring) C:438, 4: Missing method docstring (missing-docstring) C:443, 4: Missing method docstring (missing-docstring)
core.domain.email_manager_test @vibhor98 C:537, 8: Missing function docstring (missing-docstring) C:584, 8: Missing function docstring (missing-docstring) C:629, 8: Missing function docstring (missing-docstring) C:845, 8: Missing function docstring (missing-docstring) C:865, 8: Missing function docstring (missing-docstring) C:916, 8: Missing function docstring (missing-docstring)
core.domain.story_services_test @vibhor98 C:426, 4: Missing method docstring (missing-docstring) C:430, 4: Missing method docstring (missing-docstring)
core.domain.stats_services_test @vibhor98 C:1571, 4: Missing method docstring (missing-docstring) C:1576, 4: Missing method docstring (missing-docstring) C:1583, 4: Missing method docstring (missing-docstring) C:1591, 4: Missing method docstring (missing-docstring) C:1601, 4: Missing method docstring (missing-docstring) C:1605, 4: Missing method docstring (missing-docstring) C:1615, 4: Missing method docstring (missing-docstring) C:1626, 4: Missing method docstring (missing-docstring) C:1895, 4: Missing method docstring (missing-docstring) C:1899, 4: Missing method docstring (missing-docstring) C:1904, 4: Missing method docstring (missing-docstring) C:1911, 4: Missing method docstring (missing-docstring) C:1920, 4: Missing method docstring (missing-docstring)
core.domain.user_services_test @vibhor98 C:946, 8: Missing class docstring (missing-docstring) C:954,12: Missing method docstring (missing-docstring) C:961,12: Missing method docstring (missing-docstring)
core.domain.rating_services @vibhor98 C: 59, 4: Missing function docstring (missing-docstring)
core.domain.email_manager @vibhor98 C:267, 4: Missing function docstring (missing-docstring) C:314, 4: Missing function docstring (missing-docstring)
core.domain.classifier_domain_test @vibhor98 C: 29, 4: Missing method docstring (missing-docstring) C:165, 4: Missing method docstring (missing-docstring)
core.domain.learner_playlist_services_test @vibhor98 C: 81, 4: Missing method docstring (missing-docstring) C: 89, 4: Missing method docstring (missing-docstring)
core.domain.learner_progress_services_test @vibhor98 C: 90, 4: Missing method docstring (missing-docstring) C: 99, 4: Missing method docstring (missing-docstring) C:108, 4: Missing method docstring (missing-docstring) C:116, 4: Missing method docstring (missing-docstring) C:129, 4: Missing method docstring (missing-docstring) C:145, 4: Missing method docstring (missing-docstring)

Extensions

extensions.objects.models.objects @vibhor98 C:513, 8: Missing function docstring (missing-docstring) C:520, 8: Missing function docstring (missing-docstring)
extensions.objects.models.objects_test @vibhor98 C:441, 4: Missing method docstring (missing-docstring)
extensions.interactions.base @vibhor98 C:188, 4: Missing method docstring (missing-docstring)
extensions.interactions.base_test @vibhor98 C: 84, 4: Missing method docstring (missing-docstring) C:107, 4: Missing method docstring (missing-docstring) C:112, 4: Missing method docstring (missing-docstring) C:137, 4: Missing method docstring (missing-docstring) C:183, 8: Missing function docstring (missing-docstring)
extensions.answer_summarizers.models_test @vibhor98 C: 40, 4: Missing method docstring (missing-docstring)

Scripts

scripts.pre_push_hook @vibhor98 C:216, 0: Missing function docstring (missing-docstring) C:225, 0: Missing function docstring (missing-docstring) C:232, 0: Missing function docstring (missing-docstring) C:247, 0: Missing function docstring (missing-docstring)
scripts.pre_commit_linter @vibhor98 W:1668, 4: Unreachable code (unreachable)
scripts.install_third_party @vibhor98 C:336, 0: Missing function docstring (missing-docstring)
scripts.docstrings_checker_test @vibhor98 C: 23, 0: Missing class docstring (missing-docstring)
scripts.deploy @vibhor98 C:200, 0: Missing function docstring (missing-docstring)
scripts.update_feconf @vibhor98 C: 69, 0: Missing function docstring (missing-docstring)
Enable the check for mandatory args and returns once all docstrings are completed @apb7

Completed:

oppia.feconf @rahulnitdgp
oppia.scripts.build (@hoangviet1993 #5580)
oppia.core.domain.acl_decorators: Check and correct the return types @apb7
core.controllers.base @apb7 Add docstrings for methods at line no.- 134, 537
core.controllers.cron @WickedBrat Add docstrings for class at line no.- 109
core.controllers.collection_editor @vibhor98 Add docstrings for classes at line no.- 165, 201
core.controllers.learner_dashboard @hundredrab Add docstrings for class at line no.- 121 Add docstrings for methods at line no.- 33, 124
core.controllers.pages @Vishnu-M Add docstrings for method at line no.- 28
core.domain.acl_decorators @vibhor98
core.domain.classifier_domain @apb7 Add docstrings for methods at line no.- 45, 173
core.domain.collection_domain @vibhor98 Add docstrings for methods at line no.- Add docstrings for class at line no.- 32
core.domain.config_domain @vibhor98
core.domain.email_manager @vibhor98 Add docstrings for methods at line no.- 37, 928, 939
core.domain.email_subscription_services @Kunalgarg2100
core.domain.feedback_jobs_continuous @netajik #5680 Add docstrings for method at line no.- 21
oppia.core.controllers.translator @netajik
core.domain.feedback_jobs_continuous @apb7
core.domain.fs_domain @vibhor98
core.domain.param_domain @jervis446 Add docstrings for method at line no.- 146
core.domain.stats_domain @vibhor98
core.domain.stats_jobs_continuous @vibhor98
core.domain.stats_jobs_one_off @abhimanyuthakre
core.domain.user_jobs_continuous @GanitGenius
core.domain.user_jobs_one_off @GanitGenius
core.domain.user_query_services @proishan11
core.domain.user_services @proishan11
core.domain.value_generators_domain @vasutomar
core.jobs @GanitGenius Add docstrings for classes at line no.- 518, 581, 613, 643, 846, 934
core.tests.test_util_jobs @vibhor98
core.platform.models @joydeep1701
core.platform.email.gae_email_services @square-1111
core.storage.collection.gae_models @vibhor98
core.storage.email.gae_models @vibhor98
core.storage.exploration.gae_models @vibhor98
core.storage.feedback.gae_models @vibhor98
core.storage.file.gae_models @vibhor98
core.storage.job.gae_models @divyadeep1
core.tests.test_utils @apb7
oppia.export.cloud_datastore_admin @mahjong
oppia.extensions.interactions.base @vibhor98
oppia.extensions.actions.base @vibhor98
oppia.extensions.answer_summarizers.models @vibhor98
oppia.extensions.issues.base @vibhor98
oppia.core.domain.skill_domain @vibhor98
oppia.extensions.objects.models.objects @vibhor98
oppia.extensions.visualizations.models @vibhor98
oppia.scripts.pylint_extensions @tonadev
oppia.scripts.cut_release_branch @tonadev
oppia.scripts.docstrings_checker @lilithxxx
oppia.scripts.prepare_automatic_backups @import-keshav
oppia.scripts.pre_commit_linter @import-keshav
oppia.scripts.pre_push_hook @import-keshav
oppia.main @abeerunscore96
oppia.core.domain.acl_decorators @dchen97
oppia.core.domain.stats_jobs_one_off @vibhor98 - #5734
Add module docstrings to- TextInput, Continue, PencilCodeEditor, MusicNotesInput, NumericInput, CodeRepl, MultipleChoiceInput, InteractiveMap, GraphInput, LogicProof, FractionInput, SetInput, ImageClickInput, ItemSelectionInput, MathExpressionInput, EndExploration. @vibhor98 #5734
oppia.scripts.build @import-keshav – #5808
oppia.core.domain.acl_decorators @dchen97 #5803
oppia.extensions.objects.models.objects @rafalk342
oppia.schema_utils @vibhor98 #5849
oppia.core.domain.fs_services @vibhor98 #5849
oppia.core.storage.question.gae_models @vibhor98 #5849
oppia.scripts.docstrings_checker @import-keshav
oppia.scripts.common @import-keshav
oppia.jinja_utils @vibhor98

Issue Analytics

State:
Created 6 years ago
Comments:226 (163 by maintainers)

Top GitHub Comments

2reactions

vibhor98commented, Jan 9, 2019

Thanks to all the contributors of this issue! 😃

1reaction

vibhor98commented, Dec 13, 2018

Hi @YashJipkate, I’ve assigned you. Please go ahead! Thanks!

Top Results From Across the Web

Documenting Python Code: A Complete Guide

Documenting Your Python Code Base Using Docstrings: A deep dive into docstrings for classes, class methods, functions, modules, packages, and scripts, as well ......

Python Docstrings - GeeksforGeeks

Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and ...

Generating Python Docstrings With Deep Learning! - Medium

Thus I decided to create a web app where users can select which GitHub repos they want to enable ComGen for via a...

Google Python Style Guide

Python uses docstrings to document code. A docstring is a string that is the first statement in a package, module, class or function....

Developer's Overview — python-can 4.0.0 documentation

For larger changes update doc/history.rst . Sanity check that documentation has stayed inline with code. Create a temporary virtual environment. Run python ......