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