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

[Eric Blake]

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";
-- 
2.36.1