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
+```
