I was wondering if anyone had any insight into proper method documentation. While working on the OpenNebula driver, I have been attempting to expound upon existing docstrings. However, I can't find any definitive Python style guide, nor is there a definitive authority within the libcloud library.
Any help with the documentation style I should go with would be greatly
appreciated.
Here are a few examples of inconsistencies:
OpenStack.ex_save_image
@keyword node: node to use as a base for image
@param node: L{Node}
@keyword name: name for new image
@param name: C{string}
* There are no spaces between (keyword, param) pairs. Furthermore,
unlike the next example, which uses (keyword, type) pairs, this method
uses (keyword, param) pairs.
OpenStack.create_node
@keyword ex_metadata: Key/Value metadata to...
@type ex_metadata: C{dict}
@keyword ex_files: File Path => File contents to create on
the node
@type ex_files: C{dict}
* In addition, the above function places an extra line between (keyword,
type) pairs. Below, the base class uses (keyword, type) pairs with a
space between each pair.
Base.create_node
@keyword size: The size of resources...
(required)
@type size: L{NodeSize}
@keyword image: OS Image to boot on node. (required)
@type image: L{NodeImage}
* Another example of (keyword, type) pair.
OpenStack.ex_update_node
@keyword name: New name for the server
@type name: C{str}
* In the following example, we have a method parameter. Therefore, the
'param' term is used in place of 'keyword'. However, in this example,
the term 'type' comes before the term 'param', which is different than
above.
OpenStack.ex_rebuild
@type image: C{NodeImage}
@param image: New image to use.
* However, it's the same as the example in EC2.
EC2.ex_describe_tags
@type node: C{Node}
@param node: Node instance
* Another type of documentation question, how to return. Here we see a
return line given with '@return:'.
OpenStack.ex_limits
@return: C{dict} with keys 'rate' and 'absolute'
* Same in the base class.
Base.reboot_node
@return: C{bool} True if the reboot was successful, ...
* However, in this OpenStack method, a (return, type) pair are given
rather than '@return:'.
OpenStack.ex_get_metadata
@return Key/Value metadata associated with node.
@type C{dict}
--
Hutson Betts
Computer Science and Engineering
Texas A&M University
signature.asc
Description: This is a digitally signed message part
