Public header cleanups.
authorTimothy B. Terriberry <tterribe@xiph.org>
Mon, 17 Sep 2012 15:34:15 +0000 (08:34 -0700)
committerTimothy B. Terriberry <tterribe@xiph.org>
Mon, 17 Sep 2012 15:34:15 +0000 (08:34 -0700)
More consistent formatting, s/file/stream/g, and finish adding
 function warning attributes.

include/opus/opusfile.h

index 68fd561..481ebab 100644 (file)
@@ -204,6 +204,7 @@ struct OpusTags{
    These functions manipulate the #OpusHead and #OpusTags structures,
     which describe the audio parameters and tag-value metadata, respectively.*/
 /*@{*/
+
 /**Parses the contents of the ID header packet of an Ogg Opus stream.
    \param[out] _head Returns the contents of the parsed packet.
                      The contents of this structure are untouched on error.
@@ -231,6 +232,7 @@ struct OpusTags{
                           </ul>*/
 OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
+
 /**Converts a granule position to a sample offset for a given Ogg Opus stream.
    The sample offset is simply <code>_gp-_head->pre_skip</code>.
    Granule position values smaller than OpusHead#pre_skip correspond to audio
@@ -264,11 +266,13 @@ ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
    \retval #OP_EFAULT     If there wasn't enough memory to store the tags.*/
 OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
+
 /**Initializes an #OpusTags structure.
    This should be called on a freshly allocated #OpusTags structure before
     attempting to use it.
    \param _tags The #OpusTags structure to initialize.*/
 void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
+
 /**Add a (tag, value) pair to an initialized #OpusTags structure.
    \note Neither opus_tags_add() nor opus_tags_add_comment() support values
     containing embedded NULs, although the bitstream format does support them.
@@ -280,6 +284,7 @@ void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
    \param _comment A NUL-terminated UTF-8 containing the corresponding value.*/
 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
+
 /**Add a comment to an initialized #OpusTags structure.
    \note Neither opus_tags_add_comment() nor opus_tags_add() support comments
     containing embedded NULs, although the bitstream format does support them.
@@ -290,6 +295,7 @@ int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
                     "TAG=value" form.*/
 int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
+
 /**Look up a comment value by its tag.
    \param _tags  An initialized #OpusTags structure.
    \param _tag   The tag to look up.
@@ -307,6 +313,7 @@ int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
    \retval <code>NULL</code> if no matching tag is found.*/
 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
+
 /**Look up the number of instances of a tag.
    Call this first when querying for a specific tag and then iterate over the
     number of instances with separate calls to opus_tags_query() to retrieve
@@ -316,6 +323,7 @@ const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
    \return The number of instances of this particular tag.*/
 int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
+
 /**Clears the #OpusTags structure.
    This should be called on an #OpusTags structure after it is no longer
     needed.
@@ -331,7 +339,7 @@ void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
    A stream does not need to implement seeking, but the decoder will not be
     able to seek if it does not do so.
    These functions also include some convenience routines for working with
-    standard FILE pointers or complete files stored in a single block of
+    standard FILE pointers or complete streams stored in a single block of
     memory.*/
 /*@{*/
 
@@ -349,6 +357,7 @@ typedef struct OpusFileCallbacks OpusFileCallbacks;
             value is zero.*/
 typedef size_t (*op_read_func)(void *_ptr,size_t _size,size_t _nmemb,
  void *_stream);
+
 /**Sets the position indicator for \a _stream.
    The new position, measured in bytes, is obtained by adding \a _offset
     bytes to the position specified by \a _whence.
@@ -359,9 +368,11 @@ typedef size_t (*op_read_func)(void *_ptr,size_t _size,size_t _nmemb,
    \retval -1 Seeking is not supported or an error occurred.
               <code>errno</code> need not be set.*/
 typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
+
 /**Obtains the current value of the position indicator for \a _stream.
    \return The current position indicator.*/
 typedef opus_int64 (*op_tell_func)(void *_stream);
+
 /**Closes the underlying stream.
    \retval 0   Success.
    \retval EOF An error occurred.
@@ -407,6 +418,7 @@ struct OpusFileCallbacks{
 OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
  const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
  OP_ARG_NONNULL(3);
+
 /**Opens a stream with <code>fdopen()</code> and fills in a set of callbacks
     that can be used to access it.
    This is useful to avoid writing your own portable 64-bit seeking wrappers,
@@ -421,6 +433,7 @@ OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
    \return A stream handle to use with the callbacks, or NULL on error.*/
 OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
  int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
+
 /**Opens a stream with <code>freopen()</code> and fills in a set of callbacks
     that can be used to access it.
    This is useful to avoid writing your own portable 64-bit seeking wrappers,
@@ -435,29 +448,29 @@ OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
    \param      _stream A stream previously returned by op_fopen(), op_fdopen(),
                         or op_freopen().
    \return A stream handle to use with the callbacks, or NULL on error.*/
-void *op_freopen(OpusFileCallbacks *_cb,const char *_path,const char *_mode,
void *_stream) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3)
- OP_ARG_NONNULL(4);
+OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
+ OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
 
 /**Creates a stream that reads from the given block of memory.
-   This block of memory must contain the complete file to decode.
-   This is useful for caching small files (e.g., sound effects) in RAM.
+   This block of memory must contain the complete stream to decode.
+   This is useful for caching small streams (e.g., sound effects) in RAM.
    \param[out] _cb   The callbacks to use for this stream.
                      If there is an error creating the stream, nothing will be
                       filled in here.
    \param      _data The block of memory to read from.
    \param      _size The size of the block of memory.
    \return A stream handle to use with the callbacks, or NULL on error.*/
-void *op_mem_stream_create(OpusFileCallbacks *_cb,
+OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
  const unsigned char *_data,size_t _size);
 
 /*@}*/
 
-/**Test to see if this is an Opus file.
+/**Test to see if this is an Opus stream.
    For good results, you will need at least 57 bytes (for a pure Opus-only
-    file).
+    stream).
    Something more like 512 bytes will give more reliable results for
-    multiplexed files.
+    multiplexed streams.
    This function is meant to be a quick-rejection filter.
    Its purpose is not to guarantee that a stream is a valid Opus stream, but to
     ensure that looks enough like Opus that it isn't going to be recognized as
@@ -498,7 +511,8 @@ int op_test(OpusHead *_head,
                        be opened, or one of the other failure codes from
                        op_open_callbacks() otherwise.
    \return An #OggOpusFile pointer on success, or NULL on error.*/
-OggOpusFile *op_open_file(const char *_path,int *_error);
+OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
+ OP_ARG_NONNULL(1);
 
 /**Open a stream from a memory buffer.
    \param      _data  The memory buffer to open.
@@ -507,8 +521,8 @@ OggOpusFile *op_open_file(const char *_path,int *_error);
                       You may pass in NULL if you don't want the failure code.
                       See op_open_callbacks() for a full list of failure codes.
    \return An #OggOpusFile pointer on success, or NULL on error.*/
-OggOpusFile *op_open_memory(const unsigned char *_data,size_t _size,
- int *_error);
+OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
size_t _size,int *_error);
 
 /**Open a stream using the given set of callbacks to access it.
    \param _source        The stream to read from (e.g., a <code>FILE *</code>).
@@ -583,8 +597,9 @@ OggOpusFile *op_open_memory(const unsigned char *_data,size_t _size,
                             basic validity checks.</dd>
                          </dl>
    \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
-OggOpusFile *op_open_callbacks(void *_source,const OpusFileCallbacks *_cb,
- const unsigned char *_initial_data,size_t _initial_bytes,int *_error);
+OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
+ const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
+ size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
 
 /**Release all memory used by an #OggOpusFile.*/
 void op_free(OggOpusFile *_of);
@@ -597,7 +612,8 @@ void op_free(OggOpusFile *_of);
                        be opened, or one of the other failure codes from
                        op_open_callbacks() otherwise.
    \return An #OggOpusFile pointer on success, or NULL on error.*/
-OggOpusFile *op_test_file(const char *_path,int *_error);
+OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
+ OP_ARG_NONNULL(1);
 
 /**Partially open a stream from a memory buffer.
    \param      _data  The memory buffer to open.
@@ -606,13 +622,13 @@ OggOpusFile *op_test_file(const char *_path,int *_error);
                       You may pass in NULL if you don't want the failure code.
                       See op_open_callbacks() for a full list of failure codes.
    \return An #OggOpusFile pointer on success, or NULL on error.*/
-OggOpusFile *op_test_memory(const unsigned char *_data,size_t _size,
- int *_error);
+OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
size_t _size,int *_error);
 
-/**Partially opens the Opus file.
+/**Partially open a stream using the given set of callbacks to access it.
    This tests for Opusness and loads the headers for the first link.
    It does not seek (although it tests for seekability).
-   Use op_test_open() to finish opening the file, or op_free() to dispose of
+   Use op_test_open() to finish opening the stream, or op_free() to dispose of
     it.
    \param _source        The stream to read from (e.g., a <code>FILE *</code>).
    \param _cb            The callbacks with which to access the stream.
@@ -653,8 +669,9 @@ OggOpusFile *op_test_memory(const unsigned char *_data,size_t _size,
                          See op_open_callbacks() for a full list of failure
                           codes.
    \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
-OggOpusFile *op_test_callbacks(void *_source,const OpusFileCallbacks *_cb,
- const unsigned char *_initial_data,size_t _initial_bytes,int *_error);
+OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
+ const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
+ size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
 
 /**Finish opening a stream partially opened with op_test_callbacks() or one of
     the associated convenience functions.
@@ -681,13 +698,13 @@ OggOpusFile *op_test_callbacks(void *_source,const OpusFileCallbacks *_cb,
                               seeking.
    \retval #OP_EBADTIMESTAMP The first or last timestamp in a link failed basic
                               validity checks.*/
-int op_test_open(OggOpusFile *_of);
+int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
-/**Returns the number of links in this chained file.
+/**Returns the number of links in this chained stream.
    \return For seekable sources, this returns the total number of links in the
-            whole file.
+            whole stream.
            For unseekable sources, this always returns 1.*/
-int op_link_count(OggOpusFile *_of);
+int op_link_count(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
 /**Returns whether or not the data source being read is seekable.
    This is true if
@@ -696,7 +713,7 @@ int op_link_count(OggOpusFile *_of);
    c) The tell callback was successfully able to report the position indicator
     afterwards.
    \return A non-zero value if seekable, and 0 if unseekable.*/
-int op_seekable(OggOpusFile *_of);
+int op_seekable(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
 /**Get the serial number of the given link in a (possibly-chained) Ogg Opus
     stream.
@@ -708,7 +725,7 @@ int op_seekable(OggOpusFile *_of);
             the serial number of the last link.
            If the source is not seekable, this always returns the serial number
             of the current link.*/
-opus_uint32 op_serialno(OggOpusFile *_of,int _li);
+opus_uint32 op_serialno(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
 /**Get the channel count of the given link in a (possibly-chained Ogg Opus
     stream.
@@ -722,10 +739,11 @@ opus_uint32 op_serialno(OggOpusFile *_of,int _li);
             the channel count of the last link.
            If the source is not seekable, this always returns the channel count
             of the current link.*/
-int op_channel_count(OggOpusFile *_of,int _li);
+int op_channel_count(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
 /**Get the total (compressed) size of the stream, or of an individual link in
-    a (possibly-chained) Ogg Opus file, including all Ogg muxing overhead.
+    a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing
+    overhead.
    \param _li The index of the link whose compressed size should be computed.
               Use a negative number to get the compressed size of the entire
                stream.
@@ -735,10 +753,10 @@ int op_channel_count(OggOpusFile *_of,int _li);
    \retval #OP_EINVAL The source is not seekable (so we can't know the length),
                        \a _li wasn't less than the total number of links in
                        the stream, or the stream was only partially open.*/
-opus_int64 op_raw_total(OggOpusFile *_of,int _li);
+opus_int64 op_raw_total(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
 /**Get the total PCM length (number of samples at 48 kHz) of the stream, or of
-    an individual link in a (possibly-chained) Ogg Opus file.
+    an individual link in a (possibly-chained) Ogg Opus stream.
    Users looking for <code>op_time_total()</code> should use op_pcm_total()
     instead.
    Because timestamps in Opus are fixed at 48 kHz, there is no need for a
@@ -752,7 +770,7 @@ opus_int64 op_raw_total(OggOpusFile *_of,int _li);
    \retval #OP_EINVAL The source is not seekable (so we can't know the length),
                        \a _li wasn't less than the total number of links in
                        the stream, or the stream was only partially open.*/
-ogg_int64_t op_pcm_total(OggOpusFile *_of,int i);
+ogg_int64_t op_pcm_total(OggOpusFile *_of,int i) OP_ARG_NONNULL(1);
 
 /**Get the ID header information for the given link in a (possibly chained) Ogg
     Opus stream.
@@ -767,7 +785,7 @@ ogg_int64_t op_pcm_total(OggOpusFile *_of,int i);
             <code>NULL</code> if either \a _li is larger than the number of
             links or the current link was requested, but the stream was only
             partially open.*/
-const OpusHead *op_head(OggOpusFile *_of,int _li);
+const OpusHead *op_head(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
 /**Get the comment header information for the given link in a (possibly
     chained) Ogg Opus stream.
@@ -782,7 +800,7 @@ const OpusHead *op_head(OggOpusFile *_of,int _li);
             <code>NULL</code> if either \a _li is larger than the number of
             links or the current link was requested, but the stream was only
             partially open.*/
-const OpusTags *op_tags(OggOpusFile *_of,int _li);
+const OpusTags *op_tags(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
 /**Retrieve the index of the current link.
    This is the link that produced the data most recently read by
@@ -798,7 +816,7 @@ const OpusTags *op_tags(OggOpusFile *_of,int _li);
             each time a new link is encountered (even though op_link_count()
             always returns 1).
    \retval #OP_EINVAL The stream was not fully open.*/
-int op_current_link(OggOpusFile *_of);
+int op_current_link(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
 /**Computes the bitrate for a given link in a (possibly chained) Ogg Opus
     stream.
@@ -810,7 +828,7 @@ int op_current_link(OggOpusFile *_of);
    \retval #OP_EINVAL The stream was not fully open, the stream was not
                        seekable, or \a _li was larger than the number of
                        links.*/
-opus_int32 op_bitrate(OggOpusFile *_of,int _li);
+opus_int32 op_bitrate(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
 /**Compute the instantaneous bitrate, measured as the ratio of bits to playable
     samples decoed since a) the last call to op_bitrate_instant(), b) the last
@@ -822,7 +840,7 @@ opus_int32 op_bitrate(OggOpusFile *_of,int _li);
    \retval #OP_EFALSE No data has been decoded since any of the events
                        described above.
    \retval #OP_EINVAL The stream was not fully open.*/
-opus_int32 op_bitrate_instant(OggOpusFile *_of);
+opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
 /**Seek to a byte offset relative to the <b>compressed</b> data.
    This also scans packets to update the PCM cursor.
@@ -836,7 +854,7 @@ opus_int32 op_bitrate_instant(OggOpusFile *_of);
    \retval #OP_ENOSEEK  This stream is not seekable.
    \retval #OP_EBADLINK Failed to initialize a decoder for a stream for an
                          unknown reason.*/
-int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset);
+int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
 
 /**Seek to a page preceding the specified PCM offset, such that decoding will
     quickly arrive at the requested position.
@@ -850,7 +868,8 @@ int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset);
    \retval #OP_EINVAL  The stream was not fully open, or the target was outside
                         the valid range for the stream.
    \retval #OP_ENOSEEK This stream is not seekable.*/
-int op_pcm_seek_page(OggOpusFile *_of,ogg_int64_t _pcm_offset);
+int op_pcm_seek_page(OggOpusFile *_of,ogg_int64_t _pcm_offset)
+ OP_ARG_NONNULL(1);
 
 /**Seek to the specified PCM offset, such that decoding will begin at exactly
     the requested position.
@@ -862,17 +881,18 @@ int op_pcm_seek_page(OggOpusFile *_of,ogg_int64_t _pcm_offset);
    \retval #OP_EINVAL  The stream was not fully open, or the target was outside
                         the valid range for the stream.
    \retval #OP_ENOSEEK This stream is not seekable.*/
-int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset);
+int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
 
 /**Obtain the current value of the position indicator for \a _of.
    \return The byte position that is currently being read from.*/
-opus_int64 op_raw_tell(OggOpusFile *_of);
+opus_int64 op_raw_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
+
 /**Obtain the PCM offset of the next sample to be read.
-   If the file is not properly timestamped, this might not increment by the
+   If the stream is not properly timestamped, this might not increment by the
     proper amount between reads, or even return monotonically increasing
     values.
    \return The PCM offset of the next sample to be read.*/
-ogg_int64_t op_pcm_tell(OggOpusFile *_of);
+ogg_int64_t op_pcm_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
 /**Reads more samples from the stream.
    \param[out] _pcm      A buffer in which to store the output PCM samples, as
@@ -897,7 +917,7 @@ ogg_int64_t op_pcm_tell(OggOpusFile *_of);
            The channel count can be retrieved on success by calling
             <code>op_head(_of,*_li)</code>.
            The number of samples returned may be 0 if the buffer was too small
-            to store even a single sample for all channels, or if end of file
+            to store even a single sample for all channels, or if end-of-file
             was reached.
            The list of possible failure codes follows.
            Most of them can only be returned by unseekable, chained streams
@@ -921,7 +941,8 @@ ogg_int64_t op_pcm_tell(OggOpusFile *_of);
    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
                               a starting timestamp that failed basic validity
                               checks.*/
-int op_read(OggOpusFile *_of,opus_int16 *_pcm,int _buf_size,int *_li);
+OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
+ opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
 
 /**Reads more samples from the stream.
    \param[out] _pcm      A buffer in which to store the output PCM samples as
@@ -946,7 +967,7 @@ int op_read(OggOpusFile *_of,opus_int16 *_pcm,int _buf_size,int *_li);
            The channel count can be retrieved on success by calling
             <code>op_head(_of,*_li)</code>.
            The number of samples returned may be 0 if the buffer was too small
-            to store even a single sample for all channels, or if end of file
+            to store even a single sample for all channels, or if end-of-file
             was reached.
            The list of possible failure codes follows.
            Most of them can only be returned by unseekable, chained streams
@@ -970,7 +991,8 @@ int op_read(OggOpusFile *_of,opus_int16 *_pcm,int _buf_size,int *_li);
    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
                               a starting timestamp that failed basic validity
                               checks.*/
-int op_read_float(OggOpusFile *_of,float *_pcm,int _buf_size,int *_li);
+OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
+ float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
 
 /**Reads more samples from the stream and downmixes to stereo, if necessary.
    This function is intended for simple players that want a uniform output
@@ -991,7 +1013,7 @@ int op_read_float(OggOpusFile *_of,float *_pcm,int _buf_size,int *_li);
    \return The number of samples read per channel on success, or a negative
             value on failure.
            The number of samples returned may be 0 if the buffer was too small
-            to store even a single sample for both channels, or if end of file
+            to store even a single sample for both channels, or if end-of-file
             was reached.
            The list of possible failure codes follows.
            Most of them can only be returned by unseekable, chained streams
@@ -1015,7 +1037,8 @@ int op_read_float(OggOpusFile *_of,float *_pcm,int _buf_size,int *_li);
    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
                               a starting timestamp that failed basic validity
                               checks.*/
-int op_read_stereo(OggOpusFile *_of,opus_int16 *_pcm,int _buf_size);
+OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
+ opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
 
 /**Reads more samples from the stream and downmixes to stereo, if necessary.
    This function is intended for simple players that want a uniform output
@@ -1036,7 +1059,7 @@ int op_read_stereo(OggOpusFile *_of,opus_int16 *_pcm,int _buf_size);
    \return The number of samples read per channel on success, or a negative
             value on failure.
            The number of samples returned may be 0 if the buffer was too small
-            to store even a single sample for both channels, or if end of file
+            to store even a single sample for both channels, or if end-of-file
             was reached.
            The list of possible failure codes follows.
            Most of them can only be returned by unseekable, chained streams
@@ -1060,7 +1083,8 @@ int op_read_stereo(OggOpusFile *_of,opus_int16 *_pcm,int _buf_size);
    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
                               a starting timestamp that failed basic validity
                               checks.*/
-int op_read_float_stereo(OggOpusFile *_of,float *_pcm,int _buf_size);
+OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
+ float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
 
 # if OP_GNUC_PREREQ(4,0)
 #  pragma GCC visibility pop