From mboxrd@z Thu Jan 1 00:00:00 1970 From: Lucas Meneghel Rodrigues Subject: Re: [KVM-AUTOTEST] Style guides for autotest Date: Sun, 07 Jun 2009 22:03:06 -0300 Message-ID: <1244422986.3678.24.camel@localhost.localdomain> References: <1827721782.1383981244378700208.JavaMail.root@zmail05.collab.prod.int.phx2.redhat.com> Mime-Version: 1.0 Content-Type: text/plain Content-Transfer-Encoding: 7bit Cc: jasowang@redhat.com, aeromenk@redhat.com, Mike Burns , yzhou@redhat.com, supriyak@in.ibm.com, byang@redhat.com, Yogi , David Huff , Dor Laor , Autotest mailing list , KVM mailing list To: Michael Goldish Return-path: Received: from mx2.redhat.com ([66.187.237.31]:59337 "EHLO mx2.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752216AbZFHBDY (ORCPT ); Sun, 7 Jun 2009 21:03:24 -0400 In-Reply-To: <1827721782.1383981244378700208.JavaMail.root@zmail05.collab.prod.int.phx2.redhat.com> Sender: kvm-owner@vger.kernel.org List-ID: 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