Re: [Qemu-block] [Qemu-devel] [PATCH 09/10] scripts/qemu.py: use a more consistent docstring style

[Eduardo Habkost]

On Mon, Oct 08, 2018 at 03:44:14PM -0400, John Snow wrote:
> 
> 
> On 10/04/2018 12:18 PM, Cleber Rosa wrote:
> > Signed-off-by: Cleber Rosa <address@hidden>
> > ---
> >  dtc             |  2 +-
> >  scripts/qemu.py | 65 +++++++++++++++++++++++++++++++------------------
> >  2 files changed, 42 insertions(+), 25 deletions(-)
> > 
> > diff --git a/dtc b/dtc
> > index 88f18909db..e54388015a 160000
> > --- a/dtc
> > +++ b/dtc
> > @@ -1 +1 @@
> > -Subproject commit 88f18909db731a627456f26d779445f84e449536
> > +Subproject commit e54388015af1fb4bf04d0bca99caba1074d9cc42
> > diff --git a/scripts/qemu.py b/scripts/qemu.py
> > index f099ce7278..7abe26de69 100644
> > --- a/scripts/qemu.py
> > +++ b/scripts/qemu.py
> > @@ -53,9 +53,9 @@ class QEMUMachineAddDeviceError(QEMUMachineError):
> >      """
> >  
> >  class MonitorResponseError(qmp.qmp.QMPError):
> > -    '''
> > +    """
> >      Represents erroneous QMP monitor reply
> > -    '''
> > +    """
> 
> This seems obviously correct, as per the Python Dogma Handbook ...
> 
[...]
> >      def add_fd(self, fd, fdset, opaque, opts=''):
> > -        '''Pass a file descriptor to the VM'''
> > +        """
> > +        Pass a file descriptor to the VM
> > +        """
> 
> However, is it established practice among ne'er-do-wells to format
> one-line docstrings as three-liners? (And without punctuation to boot --
> for shame!)
> 
> PEP257 suggests that one-liners are allowed, but doesn't seem to
> necessitate their usage. Does this kind of change have any kind of benefit?

I don't mind having one-line docstrings.  But if we're already
touching multiple docstrings, consistency with the rest of the
module code sounds nice.

I'm queueing this on python-next.

-- 
Eduardo