Docstring style in the back end

[mathemancer]

I think we should consider adding a bunch of easy-for-first-timer issues to write and tidy up docstrings in the back end code. @kgodey I know it's a little late for GSoC, but I just thought of it this morning. For the issues to make sense, we'd need to choose a docstring style. I'm partial to reST, since I think it's most common (in fact, it's what SQLAlchemy uses, so that would be consistent).

Are we okay with me going ahead and assuming reST style docstrings, and if so, should I go ahead and make a bunch of such issues?

[dmos62]

I like ReStructuredText. Pretty weird name, but I do prefer its syntax to markdown for example.

I think it's good to have a defined docstring format/style/language, and it would be useful if someone cleaned our docstrings up. I'd love it if it was done automatically by some linter/formatter, but doing it manually is fine too.

Do you think a newcomer could write useful docstrings though (from scratch)? Maybe a newcomer could write it, but that would take a lot of effort since he'd have to understand the code pretty well. This doesn't seem the main focus of what you're suggesting though. Care to comment?

[mathemancer]

Do you think a newcomer could write useful docstrings though (from scratch)? Maybe a newcomer could write it, but that would take a lot of effort since he'd have to understand the code pretty well. This doesn't seem the main focus of what you're suggesting though. Care to comment?

I think they can write them from scratch for some simple functions without too much effort. I like the project even for more complicated functions, because it's good for "onboarding". It will also give us a chance to go back-and-forth with contributors and help them understand a given function, its callers, etc. during the PR review process.

My plan is to make the issues pretty small so a potential contributor can focus on one narrow portion of the codebase at a time, which should help.

[kgodey]

I'm fine with reST, it will also allow us to use Sphinx to auto generate code documentation in the future.

Are we okay with me going ahead and assuming reST style docstrings, and if so, should I go ahead and make a bunch of such issues?

Yes to both.