devref for public API docstring

This patch updates our review guidelines with respect to
public API docstrings. While we want to encourage docstrings,
we don't want hard enforcement that may result in a raised
entry barrier for lib contributors.

I'll investigate the ability to implement a warn-only hacking check
for docstrings. This would allow us to identify and cleanup
pydoc "debt" if we desired.

Change-Id: I73734e4acc34ed7716e3daceb664cebbf045c8ff

doc/source/review-guidelines.rst

@@ -15,6 +15,13 @@ When reviewing neutron-lib changes, please be aware:
     are uninteresting, but any code or interface should have a unit test.
   - Is there a corresponding Depends-On review in neutron removing
     this code, and adding backwards compatibility shims for Mitaka?
+  - Do the public APIs have their parameters and return values documented
+    using reStructuredText docstring format (see below)?
+
+* Public APIs should be documented using `reST style docstrings <https://www.python.org/dev/peps/pep-0287/>`_
+  that include an overview as well as parameter and return documentation.
+  The format of docstrings can be found in the `OpenStack developer hacking docs <http://docs.openstack.org/developer/hacking/#docstrings>`_.
+  Note that public API documentation is a bonus, not a requirement.
 
 * Public classes and methods must not be destructively changed without
   following the full OpenStack deprecation path.