-
Notifications
You must be signed in to change notification settings - Fork 13
/
docstrings.Rmd
65 lines (51 loc) · 1.7 KB
/
docstrings.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
---
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?
```