docs(python): Address ignored Ruff doc rules #9919
Conversation
D101, D102 & D103 are all useful rules, so have added docstrings where possible. On some internal utils, I have marked private and/or used a noqa. This should stop us from adding undocumented public functions. D100 & D104: we are not using module and package docstrings at all, is this something we want/need? As it is in the list of "remove errors" in pyproject.toml. D105: we should probably do this, but there are a lot here.
zundertj
requested review from
ritchie46,
stinodego and
alexander-beedie
as code owners
It seems we are not exactly sticking to FrozenSet, as we return a FrozenSet of DataTypeGroup, but take in different types in this constructor.
This is something that is super helpful to people like me, who come from the outside and have to just dive into the code base when trying to help out with not much guidance from docstrings. This is especially true on the rust side, where barely any of the modules have any top-level documentation and there are way more files, and I often find myself floundering to find out what each module is responsible for. I'd be happy to help on this one (on python side at least). I'm one of those weirdos that sort of enjoys doing documentation. |
|
Just to be sure, addressing D100, D104 & D105 would be a separate PR. |
There was a problem hiding this comment.
Nice addition! Just one nitpicky thing, then we can go ahead and merge this.
This is something that is super helpful to people like me
Indeed, I think we should add module docstrings. I have done this in a few places, but many still missing. Feel free to add some!
stinodego
changed the title
stinodego
changed the title
D101, D102 & D103 are all useful rules, so have added docstrings where possible. On some internal utils, I have marked private and/or used a noqa. This should stop us from adding undocumented public functions.
D100 & D104: we are not using module and package docstrings at all, is this something we want/need? As it is in the list of "remove errors" in pyproject.toml.
D105: we should probably do this, but there are a lot here.