libcloud docstring

gistfile1.md

Docstrings

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 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:

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

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.

required args