If you’d like more information about docstrings, then check out PEP 257 - Docstring Conventions.
Understanding Python Docstrings
00:00 Understand Python Docstrings. Docstrings are your biggest help for documenting your Python code. They’re built-in strings that you can configure to hold usage instructions and information about your functions, classes, and modules.
01:09 docstrings can help to make the code that you’re working with easier to understand. They provide information about code objects, and if you write them well, they will clarify the context and use of an object.
If you call
help() on any code object, then Python will print the object’s docstring to your terminal. In the BPython REPL, this is presented on a separate screen, which you can exit by pressing Q.
This attribute contains your docstring, and you could read any docstring with
.__doc__. However, you’ll usually access it through the more convenient
help() function. Displaying a docstring with
help() also improves the formatting.
Other types of docstrings, such as module and package docstrings, use the same triple double-quote syntax. You place a module docstring, right at the beginning of a file, and you write a package docstring at the beginning of a
02:30 The basic syntax for all Python docstrings is the same, although you’ll find them in different locations based on what the docstring is documenting. In this course, you’ll create function, module, and package docstrings.
02:43 If your personal Python project contains classes, then you should document these as well using class docstrings. Docstrings were formalized in PEP 257, but their structure isn’t strictly defined. Subsequently, different projects have developed different standards for Python docstrings.
03:04 MkDocs supports three common types of Python docstring formats: Google-Style docstrings, the NumPy Docstring Standard, and the Sphinx Docstring Format. The Python handler for MkDocs uses Google-style docstrings by default, an example of which is seen on-screen.
03:23 The docstring should start with a one-line summary and then have sections for a longer description if needed, followed by arguments, return values, and relevant exceptions that the function may raise.
Become a Member to join the conversation.