Apache Libcloud a unified interface to the cloud

Docstring Convetions

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