Clarify cubeb_data_callback ret value for input only streams.

The description of the ret value of cubeb_data_callback specifies that it is
the number of frames written to the output buffer. However, in the input only
stream case no data should be written to the output buffer and the output
buffer arg will be NULL.

This leaves it unclear as to the value that should be returned in the input
only case. To prevent a drain nframes should be returned, however, reading the
documentation left me unsure as to if I should return 0 or nframes.

This commit attempts to clarify the doc comment for input only streams.

1 files changed, 6 insertions, 2 deletions

diff --git a/include/cubeb/cubeb.h b/include/cubeb/cubeb.h
index b7dc862..d690a0a 100644
--- a/include/cubeb/cubeb.h
+++ b/include/cubeb/cubeb.h
@@ -366,8 +366,12 @@ typedef struct {
     @param output_buffer A pointer to a buffer to be filled with audio samples,
                          or nullptr if this is an input-only stream.
     @param nframes The number of frames of the two buffer.
-    @retval Number of frames written to the output buffer. If this number is
-            less than nframes, then the stream will start to drain.
+    @retval If the stream has output, this is the number of frames written to
+            the output buffer. In this case, if this number is less than
+            nframes then the stream will start to drain. If the stream is
+            input only, then returning nframes indicates data has been read.
+            In this case, a value less than nframes will result in the stream
+            being stopped.
     @retval CUBEB_ERROR on error, in which case the data callback will stop
             and the stream will enter a shutdown state. */
 typedef long (* cubeb_data_callback)(cubeb_stream * stream,