# Explicit parameter list in function documentation

**URL:** <https://discuss.python.org/t/explicit-parameter-list-in-function-documentation/16090>\
**Category:** Documentation\
**Created:** [May 30, 2022, 10:35pm UTC](https://discuss.python.org/t/explicit-parameter-list-in-function-documentation/16090 "2022-05-30T22:35:11Z")\
**Posts on this page:** 1\
**Showing post:** 7

<div class="post-metadata">

**Author:** ![EpicWink](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/epicwink/32/17968_2.png) [@EpicWink](https://discuss.python.org/u/EpicWink)\
**Post date:** [May 31, 2022, 1:14pm UTC](https://discuss.python.org/t/explicit-parameter-list-in-function-documentation/16090/7 "2022-05-31T13:14:14Z")

</div>

> [@malemburg](#):
>
> I believe the OP is talking about explaining the parameters of a function inline (as we do now in the docs, e.g. the open function) vs. presenting the parameters as a definition list (as is done in the numpy docs, e.g. numpy norm function).

Yes this. Sorry for not being clear and making assumptions in my original post.

By `man`-style, I mean documentation (of both C functions and shell commands) where the non-flag parameters (ie positional) are described in prose just after the signature. This is also recommended by `click`.

```plaintext
reverse X [--repeat N]

Output the reverse of the string X

OPTIONS

--repeat N repeat the output N times

```

To list explicitly means to have effectively a bullet-list of all (positional and keyword etc) parameters under the signature, with a list item for each parameter (including parameter typing and description).

```plaintext
reverse(X, repeat=1)

Reverse a string

Args:
   X (string): string to reverse
   repeat (int): repeat the reverse string multiple times

Returns:
   string: reversed string

```

* * *

> [@malemburg](#):
>
> whereas the inline version is more readable for functions with few parameters or cases

I disagree, I think inline style is more relevant where it doesn’t make sense to individually describe the parameters. For example, Compare the following with `pow`’s actual documentation:

```plaintext
pow(base, exp)

Exponentiate a number

Args:
   base: number to exponentiate
   exp: power to exponentiate to

Returns:
   resultant value

```

---

_[View the full topic](https://discuss.python.org/t/explicit-parameter-list-in-function-documentation/16090)._