docstrings.Rmd

---
jupyter:
  jupytext:
    text_representation:
      extension: .Rmd
      format_name: rmarkdown
      format_version: '1.2'
      jupytext_version: 1.11.5
  kernelspec:
    display_name: Python 3 (ipykernel)
    language: python
    name: python3
  orphan: true
---

# Docstrings

Quoting from the [Python glossary], a docstring is a "A string literal which
appears as the first expression in a class, function or module.".

A {doc}`string literal <string_literals>` is a string contained within quotes
or triple quotes.

Here is a docstring in a function:

```{python}
def func(arg1):
    "This is the function docstring"
    return arg1 * 4
```

It is useful to write docstrings for several reasons:

- the process of writing the docstring forces you to explain the function to
  yourself, and therefore write clearer code with better design;
- you and others using your function can read the docstring to see how to use
  your function;
- Python (via "help()") and [IPython] (via "func?") can read the docstring and
  return it to you, when you are working interactively;
- there are good tools, such as [Sphinx], that can process the docstrings to
  make attractive documentation. See {ref}`documentation-guidelines`.

## Using docstrings

You can use docstrings at your interactive Python or IPython prompt:

```{python}
help(func)
```

In fact Python puts the docstring into the `__doc__` attribute of the
function:

```{python}
print(func.__doc__)
```

One of the most useful features of Jupyter and IPython is its ability to
return docstrings when you add a question mark and press return after the name
of the function you are interested in:

```{python}
# Uncomment and execute the cell to see help on `func`
# func?
```