Hi Lucas, 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). - 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. - 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. Thanks, Michael ----- Original Message ----- From: "Lucas Meneghel Rodrigues" <[email protected]> To: "Autotest mailing list" <[email protected]>, "KVM mailing list" <[email protected]> Cc: [email protected], [email protected], "Mike Burns" <[email protected]>, [email protected], [email protected], "Michael Goldish" <[email protected]>, [email protected], "Yogi" <[email protected]>, "David Huff" <[email protected]>, "Dor Laor" <[email protected]> Sent: Friday, June 5, 2009 8:55:01 PM (GMT+0200) Auto-Detected Subject: [KVM-AUTOTEST] Style guides for autotest One thing I did forget to mention on the patch queue e-mail is the reference to the autotest coding standard: http://autotest.kernel.org/browser/trunk/CODING_STYLE There's a convention on docstrings that, besides discussed on the mailing list, wasn't still formally proposed and integrated to this document. Will do that in a minute :) So, to the patch authors, please keep in mind the above guide when re-working your patches. -- 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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
