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 <[email protected]> Authored: Sun Dec 15 20:19:43 2013 +0100 Committer: Tomaz Muraus <[email protected]> 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 ------------------
