On Nov 18, 2011, at 7:03 PM, Hutson Betts <[email protected]> wrote:
> 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}
>
The answers to all your questions may be found on the epydoc site, a tool used
to specify and generate Python documentation:
http://epydoc.sourceforge.net/manual-epytext.html
I believe most of your examples are functionally equivalent; the order of
tokens generally doesn't matter (type vs param, etc.) and the exact format of
the value is not specified (you can say C{bool} or merely describe the type,
for instance. The more markup the better, generally, as it's easier to scan in
markup and interlinks docs).
> --
> Hutson Betts
> Computer Science and Engineering
> Texas A&M University
>
>
