Miscellaneous fixes/improvements to docs

[alexreg]

The second commit is just the product of running black & isort on the codebase, which I thought might be nice, but obviously feel free to take that or leave it! I think most of the little edits in the first commit are uncontroversial. :-)

[janluke]

Oh, I didn't know that Python convention on the grammatical person to use in docstrings was the opposite of the Java one.

The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.

I have to admit that Java one makes more sense to me but conventions are conventions. Thank you so much for all these refinements!

Regarding introducing black and isort, that deserves a PR on its own, it cannot be introduced so lightly since it changes a lot of lines and the chance of causing conflicts with my feature branches is pretty high. Besides, while isort is uncontroversial, I tend to avoid black if I can. I've been the only one developing cloup, so there was not much point in using it: very often it uglifies the code and make it take too much vertical space for my taste.

So, I'd accept a PR for using isort pretty easily (possibly with pre-commit integration). But for black, I need to think about it.

[alexreg]

Yes, you're right, I'm not sure why I tacked the black/isort stuff onto this PR! It was sort of an afterthought, I suppose. Mainly to make spacing around docstrings more consistent. (And whether to start them on the same line as the """.)

I meant to explain about the verb form used for functions/methods, but glad you found that anyway... indeed, it surprised me too at first, since C# is like Java in its convention.

I'll just knock off the second commit here, and let you add isort if you fancy it. (Very easily done, of course.)

Anyway, thanks for your continued good work on Cloup. It was a pretty pleasant experience to fork typer and convert it to use Cloup instead of Click. (I've made a few releases of typer-cloup now.)

[alexreg]

(Just fixing something in the first commit now; will push again soon.)

All done!