You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@libcloud.apache.org by Hutson Betts <hu...@tamu.edu> on 2011/11/19 01:03:22 UTC
[dev] Documentation
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
Re: [dev] Documentation
Posted by Hutson Betts <hu...@tamu.edu>.
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 <hu...@tamu.edu> 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
> >
> >
> >
Re: [dev] Documentation
Posted by Tomaž Muraus <to...@apache.org>.
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 <hu...@tamu.edu> 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
>
>
>
Re: [dev] Documentation
Posted by Hutson Betts <hu...@tamu.edu>.
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 <hu...@tamu.edu> 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
> >
> >
Re: [dev] Documentation
Posted by Tom Davis <to...@dislocatedday.com>.
On Nov 18, 2011, at 7:03 PM, Hutson Betts <hu...@tamu.edu> 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
>
>