econchick / econchick/interrogate

Both class and __init__ documentation are required when they shouldnt be

Open
#128 0 comments 0 reactions 1 assignee Claimed by @econchick View on GitHub
bug needs triage
Dominant language
Python
Stars
676
Forks
55
PR merge metrics
No merged PRs in 30d

Description

Hiya,

interrogate assumes I need to document both the class and its `__init__` method. Yet this is not required by tooling usually and is actually considered an anti-pattern - the class constructor is equivalent to documenting the class and vice versa.

That is, the tool requires something like this:

```python
class MyClass:
"""
This is MyClass and it has a valid docstring.
"""
def __init__(self, some_arg: int):
"""
Args:
some_arg: an integer
"""
...
```

Whereas the two examples below are in fact correct documentation that raises errors currently:

```python
class MyClass:
def __init__(self, some_arg: int):
"""
This is MyClass and it has a valid docstring.

Args:
some_arg: an integer
"""
...
```

OR:

```python
class MyClass:
"""
This is MyClass and it has a valid docstring.

Args:
some_arg: an integer
"""
def __init__(self, some_arg: int):
...
```

There is a good exposition on this [https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html](here), which states:

```text
The __init__ method may be documented in either the class level
docstring, or as a docstring on the __init__ method itself.

Either form is acceptable, but the two should not be mixed. Choose one
convention to document the __init__ method and be consistent with it.
```

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.