Mailing-List: contact commits-help@libcloud.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@libcloud.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: tomaz@apache.org
To: commits@libcloud.apache.org
Message-Id: <ad8d085005a6416bab8316769050a93c@git.apache.org>
Subject: git commit: docs: Add costrings conventions section (moved from the
 site).
Date: Sun, 15 Dec 2013 19:21:22 +0000 (UTC)

Updated Branches:
  refs/heads/trunk bd1d3b1a1 -> cb72aea4b


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


Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/cb72aea4
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/cb72aea4
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/cb72aea4

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

----------------------------------------------------------------------
 docs/development.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/libcloud/blob/cb72aea4/docs/development.rst
----------------------------------------------------------------------
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 Python
 files for violations before a commit. If a violation is found, commit will be
 aborted.
 
+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: https://github.com/apache/libcloud/blob/trunk/libcloud/compute/base.py
+
 General guidelines
 ------------------