idea for documentation in contributing.rst

1 files changed, 52 insertions, 0 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
index cbdb519..771262d 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -238,6 +238,58 @@ Furthermore, the pixel shortage is over. We want to see:
 * `grid` instead of `g`
 * `my_function_that_does_things` instead of `mftdt`
 
+Be sure to write documentation!
+-------------------------------
+
+Documentation isn't just good, it's great - and necessary with large packages
+like OAuthlib. Please make sure the next person who reads your function/method
+can quickly understand what it does and how. Also, please ensure the parameters
+passed to each function are properly documented as well.
+
+The project has these goals/requests for docstrings that are designed to make
+the autogenerated documentation read more cleanly:
+
+#. Every parameter in the function should be listed in the docstring, and
+   should appear in the same order as they appear in the function itself.
+#. If you are unsure of the best wording for a parameter description, leave it
+   blank, but still include the `:param foo:` line. This will make it easier for
+   maintainers to see and edit.
+#. Use an existing standardized description of a parameter that appears
+   elsewhere in this project's documentation whenever possible. For example,
+   `request` is used as a parameter throughout the project with the description
+   "OAuthlib request." - there is no reason to describe it differently in your
+   function. Parameter descriptions should be a sentence that ends with a
+   period - even if it is just two words.
+#. When possible, include a `type` declaration for the parameter. For example,
+   a "request" param is often accompanied with `:type request: oauthlib.common.Request`.
+   The type is expected to be an object type reference, and should never end
+   in a period.
+#. If there is a textual docstring (recommended), use a single blank line to
+   separate the docstring and the params.
+#. When you cite class functions, please use backticks.
+
+Consolidated example
+
+	def foo(self, request, client, bar=None, key=None):
+		"""
+		This method checks the `key` against the `client`. The `request` is
+		passed to maintain context.
+
+		Example MAC Authorization header, linebreaks added for clarity
+
+		Authorization: MAC id="h480djs93hd8",
+						   nonce="1336363200:dj83hs9s",
+						   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="
+
+		.. _`MAC Access Authentication`: https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01
+		
+		:param request: OAuthlib request.
+		:type request: oauthlib.common.Request
+        :param client: Client object set by you, see ``.authenticate_client``.
+		:param bar:
+	    :param key: MAC given provided by token endpoint.
+		"""
+
 How pull requests are checked, tested, and done
 ===============================================