Thanks! That helps enormously. -- Hutson Betts Computer Science and Engineering Texas A&M University
On Sat, 2011-11-19 at 10:06 -0500, Tom Davis wrote: > > 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 > > > >
signature.asc
Description: This is a digitally signed message part
