Docstring cleanup

[maddenp-noaa]

Synopsis

While working on something else, I became distracted by divergences from conventions in our docstrings. I've tried to harmonize those in this PR, though I'm sure I've missed some stragglers that, if we agree on the conventions described below, we can chip away at in future work as we find them.

The conventions I've tried to adhere to -- which are the case in most of our docstrings already:

• For action-oriented functions/methods (most of them), use active language: "Do a thing", not "Does a thing", "Return a value", not "Returns a value", etc.
• For language objects that are rather than do -- classes, @property methods, driver workflow tasks, etc. -- simply state what the thing is: "The valid names", not "Return the valid names".
• For functions/methods that exist mainly to produce and return a value, it's ok to omit the :return: docstring item if the docstring's first line starts with "Return ...". In some places, having both is useful, but see the previous bullet for cases when neither is necessary.

Type

• Documentation

Impact

• This is a non-breaking change (existing functionality continues to work as expected)

Checklist

• I have added myself and any co-authors to the PR's Assignees list.
• I have reviewed the documentation and have made any updates necessitated by this change.

[christinaholtNOAA]

This looks great!

I like the idea of reflecting the nature of the method/function/property in the way we describe it. It's pretty consistent with naming methods/variables etc based on their part of speech (noun vs verb).