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