numpy / numpy/numpydoc

Check GL08 on class __init__ constructors

Open
#591 7 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Description

I was looking for a way to skip GL08 checks on class constructors (__init__) throughout my code. This is particularly as the numpydoc recommendation for class strings documents the constructor:

Class docstring
Use the same sections as outlined above (all except Returns are applicable). The constructor (__init__) should also be documented here, the Parameters section of the docstring details the constructor’s parameters.

It seems that there ought to be a default check ignore for __init__ constructors if no docstring has been provided (and if a class docstring has been provided). Obviously if an (optional) docstring for __init__ has been created, then it ought to be checked.

This conditional checking doesn't seem possible with the default override_<code>, exclude toml tags.
Keen to hear others thoughts!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the GL08 check and the existing override_ and exclude TOML configuration handling. Determine how to distinguish an undocumented init from one with an explicit docstring when the class has a docstring. Done means the default behavior skips only the former while still checking documented constructors, with the behavior covered by tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.