search

dbos-inc / dbos-transact-py

Ultra-Lightweight Durable Execution in Python
https://docs.dbos.dev
MIT License
244 stars 7 forks source link

Initial round of docstrings #81

Closed chuck-dbos closed 1 month ago

chuck-dbos commented 1 month ago

Also sets up pydocstyle, which seems really infernal, so I'm open to better ideas.

chuck-dbos commented 1 month ago

The pydocstyle is annoying--who checks it? Mypy? Black?

Currently the tool is pydocstyle which can be installed with PIP. I find it strange that, by default, you get one error if you leave a blank line and another error if you take it out, and so you are expected to turn off either D203 or D211 or it'll never pass.

They also have some nice, high-level settings, called "convention". Sadly there is more than one convention, at least "google", "numpy", and "pep257". Sadly, those all differ.

None of the conventions ignore missing docstrings. We have to ignore missing docstrings for now, and maybe forever. You can't simultaneously use a convention and the ignore list. So the convention has to be listed out, fortunately those are simple lists found here: https://www.pydocstyle.org/en/latest/error_codes.html#default-conventions.

If we would like to choose a convention now, let's do so and I will touch up the docstrings real quick...