Re: [KVM-AUTOTEST] Style guides for autotest

[Lucas Meneghel Rodrigues <lmr@redhat.com>]

On Sun, 2009-06-07 at 08:45 -0400, Michael Goldish wrote:
> Hi Lucas,

Hi Michael! The docstring standard wasn't defined for quite some time on
autotest, but now we're on our way to have a definition. On January
(2009) we had some conversation about the docstring format but we didn't
formalize the results of the discussion. During the previous week, I've
proposed a patch to the style guide with the format I've used on the kvm
test 

http://test.kernel.org/pipermail/autotest/2009-June/003567.html

So older autotest code will probably not follow this convention, and
eventually we can fix the non compliances with time.

> I'm a little confused about docstrings -- maybe you can clarify this for me.
> I've looked at the new KVM test that contains your recent modifications, and found a few inconsistencies:
> 
> - In the KVM test the summary line of a docstring appears on the line following the opening quotes, e.g.
> 
> """
> Summary line.
> 
> Description.
> """
> 
> but other Autotest source files (e.g. client/common_lib/pxssh.py) use the previous format (from before the recent modifications) where the summary line appears on the same line as the opening quotes:
> 
> """Summary line.
> 
> Description.
> """
> (Autotest is also somewhat inconsistent with itself -- every file in client/common_lib has its own docstring conventions.)
> 
> - In some functions in the KVM test (e.g. create() in kvm_vm.py) the summary line, followed by a blank line, is actually a summary paragraph consisting of several lines. PEP 257 (http://www.python.org/dev/peps/pep-0257/#multi-line-docstrings) states that the summary line should fit on a single line (and should be followed by a blank line).

We are aiming for a format slightly different than the recommendations
on the PEP. @brief would be the summary of the function, if needed.

> - In the KVM test the @param/@author/@note keywords are used. In other files in Autotest (e.g. client/common_lib/packages.py) they are not.

As the docstring format is new, older code won't follow it. Eventually
we might want to make patches to straighten things out, but it's not a
priority.

> - In kvm_config.py, the @param lines are indented relative to the first docstring line. In other files (e.g. kvm_vm.py) they are not.

My mistake :)

> Thanks,
> Michael

-- 
Lucas Meneghel Rodrigues
Software Engineer (QE)
Red Hat - Emerging Technologies