Tidy up docstrings

[jnsgruk]

In most of the libs, specifically the snap lib, the conventions around docstrings and formatting have become disjointed. What made me notice this particularly was around how optional args are annotated in docstrings.

In general, I'd prefer not to include optionality/defaults in the Args: section where that info is already available in the function signature with type annotations, but if we're going to do it, it should at least be consistent.

Triggered from a review in #88