I believe the sphinx/ResT specification (see for example https://pythonhosted.org/an_example_pypi_project/sphinx.html) suggests the following for docstrings (and this is what we have been following mostly through the rest of the code:

```
:param publishes: doc doc doc
:type publishes: if you for some reason want to explicitly specify a type, you can optionally do via a type clause.
:returns: documentation of return value
:rtype: optional data type for return value 
```
would be cool if we could have `:returns: xxxx` instead of `:return List:` for consistency and parseablility.