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

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