I've noticed the inconsistencies in the past, but it hasn't been a concern until I started filling in the missing function docstrings. In the process of adding some other functionality to the OpenNebula driver, I thought it would be nice to correct the "Undocumented" functions as shown in Libcloud's API Docs. However, I wanted to get the documentation "correct", or at least consistent with Libcloud, before submitting a patch.
Thank you for your responses. I believe the Epytext site will help for now. At least until there is something more formal. -- Hutson Betts Computer Science and Engineering Texas A&M University On Sat, 2011-11-19 at 16:14 +0100, Tomaž Muraus wrote: > 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 > > > > > >
signature.asc
Description: This is a digitally signed message part
