doxygen comments

6 files changed, 45 insertions, 26 deletions

diff --git a/include/FLAC/file_decoder.h b/include/FLAC/file_decoder.h
index 2d1f2e26..b63aeafb 100644
--- a/include/FLAC/file_decoder.h
+++ b/include/FLAC/file_decoder.h
@@ -320,7 +320,7 @@ FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLA
  *  argument.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -429,7 +429,7 @@ FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *dec
  *  Useful when the file decoder state is
  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
  *
- * \param  decoder  An decoder instance to query.
+ * \param  decoder  A decoder instance to query.
  * \assert
  *    \code decoder != NULL \endcode
  * \retval FLAC__SeekableStreamDecoderState
@@ -442,7 +442,7 @@ FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_
  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
  *  decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
  *
- * \param  decoder  An decoder instance to query.
+ * \param  decoder  A decoder instance to query.
  * \assert
  *    \code decoder != NULL \endcode
  * \retval FLAC__StreamDecoderState
diff --git a/include/FLAC/format.h b/include/FLAC/format.h
index 7e639b8e..bf693131 100644
--- a/include/FLAC/format.h
+++ b/include/FLAC/format.h
@@ -153,14 +153,6 @@ extern const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
 
 
 /*****************************************************************************
- * @@@ REMOVE?
- * NOTE: Within the bitstream, all fixed-width numbers are big-endian coded.
- *       All numbers are unsigned unless otherwise noted.
- *
- *****************************************************************************/
-
-
-/*****************************************************************************
  *
  * Subframe structures
  *
diff --git a/include/FLAC/seekable_stream_decoder.h b/include/FLAC/seekable_stream_decoder.h
index a91a4a39..a6441acb 100644
--- a/include/FLAC/seekable_stream_decoder.h
+++ b/include/FLAC/seekable_stream_decoder.h
@@ -442,7 +442,7 @@ FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamD
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -461,7 +461,7 @@ FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamD
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -479,7 +479,7 @@ FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamD
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -497,7 +497,7 @@ FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStrea
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -566,7 +566,7 @@ FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStream
  *  argument.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -675,7 +675,7 @@ FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const F
  *  Useful when the seekable stream decoder state is
  *  \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
  *
- * \param  decoder  An decoder instance to query.
+ * \param  decoder  A decoder instance to query.
  * \assert
  *    \code decoder != NULL \endcode
  * \retval FLAC__StreamDecoderState
diff --git a/include/FLAC/seekable_stream_encoder.h b/include/FLAC/seekable_stream_encoder.h
index 50caa595..36c5f13f 100644
--- a/include/FLAC/seekable_stream_encoder.h
+++ b/include/FLAC/seekable_stream_encoder.h
@@ -44,16 +44,44 @@ extern "C" {
  *  This module contains the functions which implement the seekable stream
  *  encoder.
  *
- * XXX (import)
+ * The basic usage of this encoder is as follows:
+ * - The program creates an instance of an encoder using
+ *   FLAC__seekable_stream_encoder_new().
+ * - The program overrides the default settings and sets callbacks using
+ *   FLAC__seekable_stream_encoder_set_*() functions.
+ * - The program initializes the instance to validate the settings and
+ *   prepare for encoding using FLAC__seekable_stream_encoder_init().
+ * - The program calls FLAC__seekable_stream_encoder_process() or
+ *   FLAC__seekable_stream_encoder_process_interleaved() to encode data, which
+ *   subsequently calls the callbacks when there is encoder data ready
+ *   to be written.
+ * - The program finishes the encoding with FLAC__seekable_stream_encoder_finish(),
+ *   which causes the encoder to encode any data still in its input pipe,
+ *   rewrite the metadata with the final encoding statistics, and finally
+ *   reset the encoder to the uninitialized state.
+ * - The instance may be used again or deleted with
+ *   FLAC__seekable_stream_encoder_delete().
  *
  * The seekable stream encoder is a wrapper around the
- * \link flac_stream_encoder stream encoder \endlink which (XXXimport)
+ * \link flac_stream_encoder stream encoder \endlink with callbacks for
+ * seeking the output.  This allows the encoder to go back and rewrite
+ * some of the metadata after encoding if necessary, and provides the
+ * metadata callback of the stream encoder internally.  However, you
+ * must provide a seek callback (see
+ * FLAC__seekable_stream_encoder_set_seek_callback()).
  *
  * Make sure to read the detailed description of the
  * \link flac_stream_encoder stream encoder module \endlink since the
  * seekable stream encoder inherits much of its behavior.
  *
  * \note
+ * If you are writing the FLAC data to a file, make sure it is open
+ * for update (e.g. mode "w+" for stdio streams).  This is because after
+ * the first encoding pass, the encoder will try to seek back to the
+ * beginning of the stream, to the STREAMINFO block, to write some data
+ * there.
+ *
+ * \note
  * The "set" functions may only be called when the encoder is in the
  * state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
  * FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but
diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h
index cc089b7e..c12557d5 100644
--- a/include/FLAC/stream_decoder.h
+++ b/include/FLAC/stream_decoder.h
@@ -411,7 +411,7 @@ void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -431,7 +431,7 @@ FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder,
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -459,7 +459,7 @@ FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder,
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -477,7 +477,7 @@ FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decod
  * The callback is mandatory and must be set before initialization.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
@@ -492,7 +492,7 @@ FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder,
  *  argument.
  *
  * \default \c NULL
- * \param  decoder  An decoder instance to set.
+ * \param  decoder  A decoder instance to set.
  * \param  value    See above.
  * \assert
  *    \code decoder != NULL \endcode
diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h
index aa512afc..32a02123 100644
--- a/include/FLAC/stream_encoder.h
+++ b/include/FLAC/stream_encoder.h
@@ -66,8 +66,7 @@ extern "C" {
  * The basic usage of this encoder is as follows:
  * - The program creates an instance of an encoder using
  *   FLAC__stream_encoder_new().
- * - The program overrides the default settings and sets callbacks for
- *   writing and metadata reporting using
+ * - The program overrides the default settings and sets callbacks using
  *   FLAC__stream_encoder_set_*() functions.
  * - The program initializes the instance to validate the settings and
  *   prepare for encoding using FLAC__stream_encoder_init().