Using help() to Get Documentation
Python has a nifty feature called documentation strings , usually referred to by its shorter name docstrings . DocStrings are an important tool that you should make use of since it helps to document the program better and makes it easier to understand.
From Names to Understanding
Finding the name of a method is useful, but a name alone may not explain what the method does. Python provides documentation strings, usually called docstrings, to make programs easier to understand. The help() feature can retrieve this documentation from a program.
The central idea is simple: docstrings provide documentation, and help() provides a way to retrieve that documentation.
What help() Retrieves
A docstring is a documentation string associated with a part of a Python program. The source describes docstrings as an important tool because they document the program and make it easier to understand. When help() is used on a documented method or another program element, it can provide simple documentation for that element.
Looking up a method
You know the name of a string method, but you need documentation about it.
Find available names: The dir function can list methods. This gives you names to investigate.
Request documentation: Use help to obtain simple documentation for the method you are investigating.
Use the explanation: Read the returned documentation to improve your understanding of the method instead of relying only on its name.
dir helps you discover method names, while help helps you read documentation for a method.
| Tool | Main purpose |
|---|---|
| dir | Lists methods |
| help | Provides simple documentation for a method |
A Documentation Lookup
Imagine that you are working with string methods. You first use dir to see which methods are available. After choosing a method, you use help to obtain simple documentation about it. This two-step process changes the task from guessing what a method name means to consulting the documentation attached to the method.
The example illustrates the division of responsibility: dir answers which methods are available, while help answers what documentation is available for a selected method. The source also notes that a better source of documentation for string methods would be available beyond merely listing their names.
What do you think happens?
You have found a method name with dir. Which tool should you use when you now want simple documentation about that method?
Reveal answer
Answer: help
The source describes dir as listing methods and help as providing simple documentation for a method.
Why Docstrings Matter
Use docstrings for any non-trivial function you write. They document the program and make it easier to understand. This practice also makes the documentation available to tools that can retrieve documentation from the program.
The source identifies pydoc as another useful documentation tool. The pydoc command included with a Python distribution works similarly to help() by using docstrings.
Mistakes with Documentation Lookup
Treating dir as if it provides full documentation
The source describes dir as a way to list methods, while help provides simple documentation for a method.
Fix:
Use dir to discover names and help to investigate the documentation for a selected method.Skipping docstrings for non-trivial functions
The source recommends docstrings for any non-trivial function because they document the program and make it easier to understand.
Fix:
Add a docstring to non-trivial functions so people and automated tools can use the documentation.Thinking documentation is useful only while writing code
The source emphasizes that docstrings help make programs easier to understand and can be retrieved by automated tools.
Fix:
Treat documentation as part of the program, especially for non-trivial functions.
Practice the Lookup Process
A classmate says, “I used dir and found a method, so I already know what it does.” Explain what dir contributed and what help could add. Then explain why adding a docstring to a non-trivial function would make the function easier to understand and more useful to automated documentation tools.
Hints
- Separate listing method names from reading method documentation.
- Use the source’s recommendation about docstrings for non-trivial functions.
- Mention that pydoc also uses docstrings.
Key Takeaways
- Docstrings are documentation strings that make programs easier to understand.
- help() can retrieve documentation from a program.
- dir lists methods, while help provides simple documentation for a selected method.
- Non-trivial functions should have docstrings.
- Automated tools and pydoc can use docstrings to provide documentation.
Key Takeaways
- Docstrings document Python programs and improve their understandability.
- Use dir to discover method names and help to obtain simple documentation for a method.
- Write docstrings for non-trivial functions.
- Automated tools and pydoc can retrieve documentation from docstrings.