Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added a clause for "indented-line" blocks for the Python style guide #537

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 28 additions & 4 deletions pyguide.md
Original file line number Diff line number Diff line change
Expand Up @@ -1982,16 +1982,40 @@ aptly described using a one-line docstring.

<a id="doc-function-args"></a>
[*Args:*](#doc-function-args)
: List each parameter by name. A description should follow the name, and be
separated by a colon and a space. If the description is too long to fit on a
single 80-character line, use a hanging indent of 2 or 4 spaces (be
consistent with the rest of the file).
: List each parameter by name. A description should follow the name on the
same line and be separated by a colon and a space. A description can also
follow on the next line. If the description is too long to fit on a single
80-character line, use a hanging indent of 2 or 4 spaces (be consistent with
the rest of the file).

The description should include required type(s) if the code does not contain
a corresponding type annotation. If a function accepts `*foo` (variable
length argument lists) and/or `**bar` (arbitrary keyword arguments), they
should be listed as `*foo` and `**bar`.

Both examples below are valid descriptions.

```python
def print_data(verbose):
"""Prints information about the user's environment.

Args:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we also clarify what to do in case of a mix of both the styles? And add an example for that as well?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I recall, there'd been some discussion here in favor of allowing mixed styles across a code base, but not within a single docstring. That may be over prescriptive though and should probably be decided by someone at google. cc: @gpshead

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in general i favor not being over prescriptive about that. the main consistency thing is the indentation level (which is already mentioned). but trying to enumerate a matrix of possible argument or exception and their descriptions style mixes for things would explode meaninglessly and become an enemy of documentation. :)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As long as "hanging indent" style is allowed by the standard, I'm happy for maintainers of tools to decide whether or not to enforce consistency. Avoiding being over prescriptive and having the option to pick the right look for the right doc would be a great thing.

verbose: If True, print out lots of logging data to the user's screen.
If False, only print one line.
"""
```

```python
def print_data(verbose):
"""Prints information about the user's environment.

Args:
verbose:
If True, print out lots of logging data to the user's screen.
If False, only print one line.
"""
```

<a id="doc-function-returns"></a>
[*Returns:* (or *Yields:* for generators)](#doc-function-returns)
: Describe the type and semantics of the return value. If the function only
Expand Down