Docstring Convetions
Libcloud follow epytext 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 andL{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:
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 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