Re: [PATCH 1/3] python: improve get/set_lvb documentation

[Nir Soffer]

On Wed, Dec 9, 2020 at 10:16 PM Nir Soffer <nsoffer(a)redhat.com&gt; wrote:
>  On Wed, Dec 9, 2020 at 7:43 PM Benny Zlotnik <bzlotnik(a)redhat.com&gt; wrote:
>  >
>  > - Specify lvb=True explicitly instead of mentioning the sanlock flag
>  > - Document when data is written and visible
>  >
>  > Signed-off-by: Benny Zlotnik <bzlotnik(a)redhat.com&gt;
>  > ---
>  >  python/sanlock.c | 6 ++++--
>  >  1 file changed, 4 insertions(+), 2 deletions(-)
>  >
>  > diff --git a/python/sanlock.c b/python/sanlock.c
>  > index fbcabb1..567d86c 100644
>  > --- a/python/sanlock.c
>  > +++ b/python/sanlock.c
>  > @@ -1607,7 +1607,9 @@ Arguments\n\
>  >  \n\
>  >  Notes\n\
>  >  \n\
>  > -The resource must be acquired with the SANLK_ACQUIRE_LVB flag\n");
>  > +The resource must be acquired with lvb=true.\n\
>  > +The size of data is limited by the sector size (512/4K).\n\
>  > +The new data is visible after the resource is released\n");
>  >  static PyObject *
>  >  py_set_lvb(PyObject *self __unused, PyObject *args, PyObject *keywds)
>  >  {
>  > @@ -1662,7 +1664,7 @@ Returns\n\
>  >    data              data written with set_lvb\n\
>
>  Missing \n 
You can check that text using:

$ PYTHONPATH=build/lib.linux-x86_64-3.8 python -c 'import
sanlock;help(sanlock.get_lvb)'
Help on built-in function get_lvb in module sanlock:

get_lvb(...)
    get_lvb(lockspace, resource, disks) -> bytes
    Read Lock Value Block for a given resource

    Arguments
      lockspace         lockspace name (str)
      resource          resource name (int)
      disks             path and offset (tuple)
      size              Amount of data to read (int)

    Returns
      data              data written with set_lvb
    Notes

    The resource must be acquired with lvb=True
    size is required and has to be > 0.

>  >  Notes\n\
>  >  \n\ 
Newline not needed here

>  > -The resource must be acquired with the SANLK_ACQUIRE_LVB
> flag\n");
>  > +The resource must be acquired with lvb=True\n");
>
>  In a later patch you added
>
>      size is required and has to be > 0.
>
>  Which should be part of this patch. 
size is added only in the next patch so this is fine.

>  But we should also mention that the size
>  must be equal or less then the resource sector size.
>
>  >  static PyObject *
>  >  py_get_lvb(PyObject *self __unused, PyObject *args, PyObject *keywds)
>  >  {
>  > --
>  > 2.28.0
>  >