libcloud-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From to...@apache.org
Subject svn commit: r1400993 - /libcloud/site/trunk/content/docstring-conventions.mdtext
Date Mon, 22 Oct 2012 18:37:19 GMT
Author: tomaz
Date: Mon Oct 22 18:37:18 2012
New Revision: 1400993

URL: http://svn.apache.org/viewvc?rev=1400993&view=rev
Log:
Add "Docstring Convetions" page.

Added:
    libcloud/site/trunk/content/docstring-conventions.mdtext

Added: libcloud/site/trunk/content/docstring-conventions.mdtext
URL: http://svn.apache.org/viewvc/libcloud/site/trunk/content/docstring-conventions.mdtext?rev=1400993&view=auto
==============================================================================
--- libcloud/site/trunk/content/docstring-conventions.mdtext (added)
+++ libcloud/site/trunk/content/docstring-conventions.mdtext Mon Oct 22 18:37:18 2012
@@ -0,0 +1,68 @@
+title: Docstring Convetions
+
+## Docstring Convetions ##
+
+Libcloud follow [epytext](http://epydoc.sourceforge.net/epytextintro.html) docstring formatiing.
+
+  - Docstrings should always be used to describe the purpose of methods, functions, classes,
and modules.
+  - Method docstring describes  all vargs and keywords (varargs and keywords are the names
of the * and ** arguments).
+  - All of the blocks contained by a field must all have equal indentation, and that indentation
must be greater than or equal to the indentation of the field's tag.
+  - All parametrs must have `@param` or `@keyword` field and `@type` field.
+ - `@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 for the parameter. p.
+  - Return must contain @return and @rtype.
+ - `@return: ... ` A description of return value for a function or method.
+ - `@rtype: ... ` The type of the return value for a function or method.
+  - Required parameters contain `(required)` notation in description.
+For example: `@keyword    image:  OS Image to boot on node. (required)`
+  -  Multiple types separated with "or"
+For example: `@type       auth:   L{NodeAuthSSHKey} or L{NodeAuthPassword}`
+  - `C{type}` for Built-in types and `L{type}` for Libcloud types.
+ - `@type ssh_username: C{str}`
+ - `@type node: L{Node}`
+  - For a description of constainer types used notation: `<container_type> of <objects_type>`
+For example: `@rtype: C{list} of L{Node}`
+  - Sometimes you need to inhterit all arguments and add new keyword arguments, for this
used `@inherits` field: `@inherits: L{class_name.method_name}`
+This field should be added before the arguments. If inherited docstring doesn't contain description\rtype,
they used from the parent docstring.
+
+For example:
+
+```python
+class NodeDriver(BaseDriver):
+        def create_node(self, **kwargs):
+            """
+            Create a new node instance.
+
+            @keyword    name:   String with a name for this new node (required)
+            @type       name:   C{str}
+
+            @return: The newly created node.
+            @rtype: L{Node}
+            """
+            pass
+
+        def deploy_node(self, **kwargs):
+            """
+            Create a new node, and start deployment.
+
+            @inherits: L{NodeDriver.create_node}
+
+            @keyword    deploy: Deployment to run once machine is online and
+                                availble to SSH.
+            @type       deploy: L{Deployment}
+            """
+            pass
+```
+
+```python
+class OpenStackNodeDriver(NodeDriver):
+        def create_node(self, **kwargs):
+            """
+            @inherits: L{NodeDriver.create_node}
+
+            @keyword    ex_metadata: Key/Value metadata to associate with a node
+            @type       ex_metadata: C{dict}
+            """
+            pass
+```



Mime
View raw message