update API docs for callback return values

git-svn-id: http://svn.annodex.net/liboggz/trunk@2028 8158c8cd-e7e1-0310-9fa4-c5954c97daef

include/oggz/oggz.h

@@ -477,27 +477,37 @@ OGGZ * oggz_open_stdio (FILE * file, int flags);
 int oggz_flush (OGGZ * oggz);
 
 /**
- * Set the blocksize to use internally for oggz_run()
+ * Run an OGGZ until completion, or error.
+ * This is a convenience function which repeatedly calls oggz_read() or
+ * oggz_write() as appropriate.
+ * For an OGGZ opened for reading, an OggzReadPacket or OggzReadPage callback
+ * should have been set before calling this function.
+ * For an OGGZ opened for writing, either an OggzHungry callback should have
+ * been set before calling this function, or you can use this function to
+ * write out all unwritten Ogg pages which are pending.
  * \param oggz An OGGZ handle previously opened for either reading or writing
- * \param blocksize The blocksize to use within oggz_run()
  * \retval 0 Success
  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
- * \retval OGGZ_ERR_INVALID Invalid blocksize (\a run_blocksize <= 0)
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ * \retval OGGZ_ERR_SYSTEM System error; check errno for details
+ * \retval OGGZ_ERR_STOP_OK Operation was stopped by a user callback
+ * returning OGGZ_STOP_OK
+ * \retval OGGZ_ERR_STOP_ERR Operation was stopped by a user callback
+ * returning OGGZ_STOP_ERR
+ * \retval OGGZ_ERR_RECURSIVE_WRITE Attempt to initiate writing from
+ * within an OggzHungry callback
  */
-int oggz_run_set_blocksize (OGGZ * oggz, long blocksize);
-
+long oggz_run (OGGZ * oggz);
 
 /**
- * Run an OGGZ until completion, or error
+ * Set the blocksize to use internally for oggz_run()
  * \param oggz An OGGZ handle previously opened for either reading or writing
+ * \param blocksize The blocksize to use within oggz_run()
  * \retval 0 Success
  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
- * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
- * \retval OGGZ_ERR_SYSTEM System error; check errno for details
- * \retval OGGZ_ERR_RECURSIVE_WRITE Attempt to initiate writing from
- * within an OggzHungry callback
+ * \retval OGGZ_ERR_INVALID Invalid blocksize (\a run_blocksize <= 0)
  */
-long oggz_run (OGGZ * oggz);
+int oggz_run_set_blocksize (OGGZ * oggz, long blocksize);
 
 /**
  * Close an OGGZ handle

include/oggz/oggz_read.h

@@ -144,10 +144,10 @@ int oggz_set_read_page (OGGZ * oggz, long serialno,
  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
  * \retval OGGZ_ERR_SYSTEM System error; check errno for details
- * \retval OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback
- * returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were
- * consumed. This will occur when a packet is read from a previously
- * buffered page of input data, and stopping is immediately requested.
+ * \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
+ * returning OGGZ_STOP_OK
+ * \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
+ * returning OGGZ_STOP_ERR
  */
 long oggz_read (OGGZ * oggz, long n);
 
@@ -159,10 +159,10 @@ long oggz_read (OGGZ * oggz, long n);
  * \retval ">  0" The number of bytes successfully ingested.
  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
- * \retval OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback
- * returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were
- * consumed. This will occur when a packet is read from a previously
- * buffered page of input data, and stopping is immediately requested.
+ * \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
+ * returning OGGZ_STOP_OK
+ * \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
+ * returning OGGZ_STOP_ERR
  */
 long oggz_read_input (OGGZ * oggz, unsigned char * buf, long n);
 

include/oggz/oggz_write.h

@@ -196,6 +196,10 @@ int oggz_write_feed (OGGZ * oggz, ogg_packet * op, long serialno, int flush,
  * within an OggzHungry callback
  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ * \retval OGGZ_ERR_STOP_OK Writing was stopped by an OggzHungry callback
+ * returning OGGZ_STOP_OK
+ * \retval OGGZ_ERR_STOP_ERR Reading was stopped by an OggzHungry callback
+ * returning OGGZ_STOP_ERR
  */
 long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n);
 
@@ -211,6 +215,10 @@ long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n);
  * within an OggzHungry callback
  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ * \retval OGGZ_ERR_STOP_OK Writing was stopped by an OggzHungry callback
+ * returning OGGZ_STOP_OK
+ * \retval OGGZ_ERR_STOP_ERR Reading was stopped by an OggzHungry callback
+ * returning OGGZ_STOP_ERR
  */
 long oggz_write (OGGZ * oggz, long n);