[Libguestfs] [PATCH libnbd 3/9] golang: aio_buffer.go: Add missing documentation

[Eric Blake]

On Sun, Jan 30, 2022 at 01:33:31AM +0200, Nir Soffer wrote:
> Add standard function documentation comments.
> 
> The documentation should be available here:
> https://pkg.go.dev/libguestfs.org/libnbd#AioBuffer
> 
> Signed-off-by: Nir Soffer <nsoffer at redhat.com>
> ---

>  
> +// MakeAioBuffer makes a new buffer backed by an unitilialized C allocated

uninitialized

> +// array.
>  func MakeAioBuffer(size uint) AioBuffer {
>  	return AioBuffer{C.malloc(C.ulong(size)), size}
>  }
>  
> +// FromBytes makes a new buffer backed by a C allocated array, initialized by
> +// copying the given Go slice.
>  func FromBytes(buf []byte) AioBuffer {
>  	size := len(buf)
>  	ret := MakeAioBuffer(uint(size))
>  	for i := 0; i < len(buf); i++ {
>  		*ret.Get(uint(i)) = buf[i]
>  	}
>  	return ret
>  }
>  
> +// Free deallocates the underlying C allocated array. Using the buffer after
> +// Free() will panic.
>  func (b *AioBuffer) Free() {
>  	if b.P != nil {
>  		C.free(b.P)
>  		b.P = nil
>  	}
>  }
>  
> +// Bytes copies the underlying C array to Go allocated memory and return a
> +// slice. Modifying the returned slice does not modify the unerlying buffer

underlying

> +// backking array.

backing

>  func (b *AioBuffer) Bytes() []byte {
>  	return C.GoBytes(b.P, C.int(b.Size))
>  }
>  
> +// Get returns a pointer to a byte in the underlying C array. The pointer can
> +// be used to modify the underlying array. The pointer must not be used after
> +// caling Free().
>  func (b *AioBuffer) Get(i uint) *byte {
>  	return (*byte)(unsafe.Pointer(uintptr(b.P) + uintptr(i)))
>  }
> -- 
> 2.34.1
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org