google / google/styleguide

Clarifying inheritance of class documentation in python.

Open
#925 2 comments 0 reactions 1 assignee Claimed by @nathanielmanistaatgoogle View on GitHub
lang:python
Dominant language
HTML
Stars
39.6k
Forks
12.9k
Avg merge
42m
Merged PRs (30d)
15

Description

Wanted to clarify what the recommendation was for documenting child classes. What should be repeated and what should be referred back to the parent class.

For example, should we do this:

```
class Fruit:
"""

Attributes:
weight: The weight of the fruit in grams.
"""

class Apple(Fruit):
"""

Attributes:
weight: The weight of the fruit in grams.
variety: The variety of the apple from the list ["granny smith", "honey_crisp"]
"""
```

Or this:

```
class Fruit:
"""

Attributes:
weight: The weight of the fruit in grams.
"""

class Apple:
"""

Attributes:
weight: See parent.
variety: The variety of the apple from the list ["granny smith", "honey_crisp"]
"""
```

Keep in mind when arguments grow large it would be much harder to maintain the doc strings if they were copied for each child class. But its also more convenient for a user to have it copied.

Appreciate your thoughts.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.