[Libguestfs] [libnbd PATCH] api: Allow completion callbacks to auto-retire

[Richard W.M. Jones]

On Tue, Jul 23, 2019 at 03:30:16PM -0500, Eric Blake wrote:
> diff --git a/generator/generator b/generator/generator
> index fdacd71..e0a2805 100755
> --- a/generator/generator
> +++ b/generator/generator
> @@ -1738,9 +1738,9 @@ unique positive 64 bit cookie for this command, or C<-1> on
>  error.  If this command returns a cookie, then C<callback>
>  will be called when the server is done replying,
>  although you must still use C<nbd_aio_command_completed> after
> -the callback to retire the command.  Note that you must ensure
> -C<buf> is valid until the command has completed.  Other
> -parameters behave as documented in C<nbd_pread>.
> +the callback to retire the command unless the callback returns C<1>.
> +Note that you must ensure C<buf> is valid until the command has
> +completed.  Other parameters behave as documented in C<nbd_pread>.
> 
>  The C<callback> function is called with the same C<user_data> passed to
>  this function, C<cookie> set to the return value of this function,
> @@ -1796,8 +1796,8 @@ unique positive 64 bit cookie for this command, or C<-1> on
>  error.  If this command returns a cookie, then C<callback>
>  will be called when the server is done replying,
>  although you must still use C<nbd_aio_command_completed> after
> -the callback to retire the command.  Other parameters behave as
> -documented in C<nbd_pread_structured>.
> +the callback to retire the command unless the callback returns C<1>.
> +Other parameters behave as documented in C<nbd_pread_structured>.
> 
>  The C<callback> function is called with the same C<user_data> passed to
>  this function, C<cookie> set to the return value of this function,

There's quite a lot of duplicated documentation here.  There are two
approaches to deduplicating it:

(1) Add a section in the main manual (docs/libnbd.pod):

  =head1 CALLBACKS

  ...

  =head2 Completion callbacks

  common text here

and link to it from the longdesc using "L<libnbd(3)/Completion callbacks>"

(2) Put the common text in an OCaml string and interpolate it into the
longdesc in the generator:

  let completion_text = "\
  common text here
  ";

  ...

  "function", ...
  longdesc = "\
  normal description
  " ^ completion_text;


The rest of the patch is fine.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
Fedora Windows cross-compiler. Compile Windows programs, test, and
build Windows installers. Over 100 libraries supported.
http://fedoraproject.org/wiki/MinGW