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


    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