libcloud-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject git commit: docs: Add costrings conventions section (moved from the site).
Date Sun, 15 Dec 2013 19:21:22 GMT
Updated Branches:
  refs/heads/trunk bd1d3b1a1 -> cb72aea4b

docs: Add costrings conventions section (moved from the site).


Branch: refs/heads/trunk
Commit: cb72aea4ba980c88df92f8480365dea78a69d7fb
Parents: bd1d3b1
Author: Tomaz Muraus <>
Authored: Sun Dec 15 20:19:43 2013 +0100
Committer: Tomaz Muraus <>
Committed: Sun Dec 15 20:21:08 2013 +0100

 docs/development.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
diff --git a/docs/development.rst b/docs/development.rst
index 755fb4f..29d12c0 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -44,6 +44,37 @@ After you have installed this hook it will automatically check modified
 files for violations before a commit. If a violation is found, commit will be
+Docstring conventions
+For documenting the API we we use Sphinx and reStructuredText syntax. Docstring
+conventions to which you should adhere to are described bellow.
+* Docstrings should always be used to describe the purpose of methods,
+  functions, classes, and modules.
+* Method docstring should describe all the normal and keyword arguments. You
+  should describe all the available arguments even if you use ``*args`` and
+  ``**kwargs``.
+* All parameters must be documented using ``:param p:`` or ``:keyword p:``
+  and ``:type p:`` annotation.
+* ``:param p: ...`` -  A description of the parameter ``p`` for a function
+  or method.
+* ``:keyword p: ...`` - A description of the keyword parameter ``p``.
+* ``:type p: ...`` The expected type of the parameter ``p``.
+* Return values must be documented using ``:return:`` and ``:rtype``
+  annotation.
+* ``:return: ...`` A description of return value for a function or method.
+* ``:rtype: ...`` The type of the return value for a function or method.
+* Required keyword arguments must contain ``(required)`` notation in
+  description. For example: ``:keyword image:  OS Image to boot on node. (required)``
+*  Multiple types are separated with ``or``
+   For example: ``:type auth: :class:`.NodeAuthSSHKey` or :class:`.NodeAuthPassword```
+* For a description of the container types use the following notation:
+  ``<container_type> of <objects_type>``. For example:
+  ``:rtype: `list` of :class:`Node```
+You can find some examples in the following file:
 General guidelines

View raw message