Concepts / Using help() to Get Documentation

Using help() to Get Documentation

The central idea is simple: docstrings provide documentation, and help() provides a way to retrieve that documentation.

  • Programming

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.

Key point

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.

Worked example

Looking up a method

You know the name of a string method, but you need documentation about it.

  1. 1
    Find available names

    The dir function can list methods. This gives you names to investigate.

  2. 2
    Request documentation

    Use help to obtain simple documentation for the method you are investigating.

  3. 3
    Use the explanation

    Read the returned documentation to improve your understanding of the method instead of relying only on its name.

Result

dir helps you discover method names, while help helps you read documentation for a method.

ToolMain purpose
dirLists methods
helpProvides simple documentation for a method

The source distinguishes discovery with dir from documentation lookup with help.

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?

  • dir

  • help

  • Neither tool

Reveal answer
Answer:

help

The source describes dir as listing methods and help as providing simple documentation for a method.

Why Docstrings Matter

Best practice

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

  • Common mistake

    Treating dir as if it provides full documentation

    What it looks like

    Using the list of names returned by dir as the complete explanation of a method.

    Why it fails

    The source describes dir as a way to list methods, while help provides simple documentation for a method.

    Do this instead

    Use dir to discover names and help to investigate the documentation for a selected method.

  • Common mistake

    Skipping docstrings for non-trivial functions

    What it looks like

    Writing a function that requires explanation but providing no documentation string.

    Why it fails

    The source recommends docstrings for any non-trivial function because they document the program and make it easier to understand.

    Do this instead

    Add a docstring to non-trivial functions so people and automated tools can use the documentation.

  • Common mistake

    Thinking documentation is useful only while writing code

    What it looks like

    Leaving documentation out because the function currently seems familiar to its author.

    Why it fails

    The source emphasizes that docstrings help make programs easier to understand and can be retrieved by automated tools.

    Do this instead

    Treat documentation as part of the program, especially for non-trivial functions.

Practice the Lookup Process

EASY

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

  1. 1
    Docstrings are documentation strings that make programs easier to understand.
  2. 2
    help() can retrieve documentation from a program.
  3. 3
    dir lists methods, while help provides simple documentation for a selected method.
  4. 4
    Non-trivial functions should have docstrings.
  5. 5
    Automated tools and pydoc can use docstrings to provide documentation.

At a glance

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

Related Topics

Related concepts

More concepts starting with U