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 -- To unsubscribe from this list: send the line "unsubscribe kvm" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
