[Libguestfs] [libnbd PATCH v2 1/8] python: Improve doc comments for nbd.py

[Richard W.M. Jones]

On Mon, Jun 06, 2022 at 09:08:26PM -0500, Eric Blake wrote:
> PEP257 recommends that doc comments start with a one line summary and
> be a complete sentence.  Tweak our existing comments to comply.  It
> also recommends the use of """ strings, and for u""" when a string
> contains Unicode; however, for since it is easier to write ' than " in
> OCaml pr statements, we stick with ''' and u''' strings rather than
> follow the PEP completely.
> 
> Also, enhance the documentation for nbd.Buffer.from_bytearray to match
> the semantic changes from commit d477f7c7, before we change those
> semantics yet again in an upcoming patch (copying is inefficient, we
> are moving towards reusing the underlying buffer directly).
> ---
>  generator/Python.ml | 23 ++++++++++++++---------
>  1 file changed, 14 insertions(+), 9 deletions(-)
> 
> diff --git a/generator/Python.ml b/generator/Python.ml
> index 3f672ba..392be87 100644
> --- a/generator/Python.ml
> +++ b/generator/Python.ml
> @@ -763,28 +763,33 @@ let
>      '''Asynchronous I/O persistent buffer'''
> 
>      def __init__(self, len):
> -        '''allocate an uninitialized AIO buffer used for nbd.aio_pread'''
> +        '''Allocate an uninitialized AIO buffer used for nbd.aio_pread.'''
>          self._o = libnbdmod.alloc_aio_buffer(len)
> 
>      @classmethod
>      def from_bytearray(cls, ba):
> -        '''create an AIO buffer from a bytearray'''
> +        '''Create an AIO buffer from a bytearray or other buffer-like object.
> +
> +        If ba is not a buffer, it is tried as the parameter to the
> +        bytearray constructor.  Otherwise, ba is copied.  Either way, the
> +        resulting AIO buffer is independent from the original.
> +        '''
>          o = libnbdmod.aio_buffer_from_bytearray(ba)
>          self = cls(0)
>          self._o = o
>          return self
> 
>      def to_bytearray(self):
> -        '''copy an AIO buffer into a bytearray'''
> +        '''Copy an AIO buffer into a bytearray.'''
>          return libnbdmod.aio_buffer_to_bytearray(self._o)
> 
>      def size(self):
> -        '''return the size of an AIO buffer'''
> +        '''Return the size of an AIO buffer.'''
>          return libnbdmod.aio_buffer_size(self._o)
> 
>      def is_zero(self, offset=0, size=-1):
> -        '''
> -        Returns true if and only if all bytes in the buffer are zeroes.
> +        '''Returns true if and only if all bytes in the buffer are zeroes.
> +
>          Note that a freshly allocated buffer is uninitialized, not zero.
> 
>          By default this tests the whole buffer, but you can restrict
> @@ -801,11 +806,11 @@ let
>      '''NBD handle'''
> 
>      def __init__(self):
> -        '''create a new NBD handle'''
> +        '''Create a new NBD handle.'''
>          self._o = libnbdmod.create()
> 
>      def __del__(self):
> -        '''close the NBD handle and underlying connection'''
> +        '''Close the NBD handle and underlying connection.'''
>          if hasattr(self, '_o'):
>              libnbdmod.close(self._o)
> 
> @@ -855,7 +860,7 @@ let
>        let longdesc = Str.global_replace py_fn_rex "C<nbd.\\1>" longdesc in
>        let longdesc = Str.global_replace py_const_rex "C<" longdesc in
>        let longdesc = pod2text longdesc in
> -      pr "        '''▶ %s\n\n%s'''\n" shortdesc (String.concat "\n" longdesc);
> +      pr "        u'''▶ %s\n\n%s'''\n" shortdesc (String.concat "\n" longdesc);
>        pr "        return libnbdmod.%s(" name;
>        pr_wrap ',' (fun () ->
>            pr "self._o";

Reviewed-by: Richard W.M. Jones <rjones at redhat.com>

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
nbdkit - Flexible, fast NBD server with plugins
https://gitlab.com/nbdkit/nbdkit