Javadoc but for Python: Write and Inspect a Function Docstring

Start with a small, explicit task

Document a small function that labels a container count. State its accepted input and returned text, then inspect the attached documentation. Render its local text documentation with the standard library; the script does not build or claim to publish a documentation website.

Run the complete example

This original example was checked with Python 3.12.14. Save it as python_docstrings.py and run it with Python 3.12. It uses only the standard library. The assertions check the stated results.

import inspect
import pydoc
def container_label(count):
    """Return a display label for a nonnegative integer count.

    Args:
        count: Number of containers; must be nonnegative.

    Returns:
        Text such as '3 containers'.
    """
    if count < 0:
        raise ValueError("count must be nonnegative")
    return f"{count} containers"
doc = inspect.getdoc(container_label)
rendered = pydoc.render_doc(container_label, renderer=pydoc.plaintext)
assert container_label(3) == "3 containers"
assert doc.splitlines()[0].startswith("Return a display label")
assert "count" in rendered and "Returns:" in rendered
print(doc.splitlines()[0])
print("local documentation contains parameters and return description")

Explain the result

The triple-quoted first statement becomes the function’s attached documentation. inspect.getdoc retrieves a cleaned version, while pydoc renders a local text description. The assertions check that the expected parameter and return explanation are present without making the exercise depend on every formatting detail of the rendered help page.

The Args and Returns headings are a chosen readable convention, not keywords that make Python validate the interface. The function body separately checks its nonnegative rule. Comments inside the implementation could explain a decision, but ordinary # comments would not become this function’s docstring.

Avoid these mistakes

Keep documentation synchronized with actual behavior, especially exceptions and return values. This example assumes an integer count as stated; it does not claim that a docstring performs runtime type enforcement. Tools such as Sphinx add a separate publishing workflow, which has not been run by this exercise.