Yeah, I have noticed this inconstancies myself as well. I think we should go over the link Tom Davis has provided and decide about the consistent style we want to use in our code-base.
This way it will at least be a bit easier for people reading through the code. Once we decide about it, we should also document it on the website (with some examples) so the future contributors can follow those guidelines. On Sat, Nov 19, 2011 at 1:03 AM, 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} > > -- > Hutson Betts > Computer Science and Engineering > Texas A&M University > > >
