more comments

diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h
index d2a2120..9ab781b 100644 (file)
--- a/include/FLAC/stream_decoder.h
+++ b/include/FLAC/stream_decoder.h
@@ -100,16 +100,16 @@ extern "C" {
  *   metadata as well as an array of pointers (one for each channel)
  *   pointing to the decoded audio.
  * - Metadata callback - This function will be called when the decoder has
- *   decoded a metadata block.  There will always be one STREAMINFO block
- *   per stream, followed by zero or more other metadata blocks.  These will
- *   be supplied by the decoder in the same order as they appear in the
- *   stream and always before the first audio frame (i.e. write callback).
- *   The metadata block that is passed in must not be modified, and it
- *   doesn't live beyond the callback, so you should make a copy of it with
- *   FLAC__metadata_object_clone() if you will need it elsewhere.  Since
- *   metadata blocks can potentially be large, by default the decoder only
- *   calls the metadata callback for the STREAMINFO block; you can instruct
- *   the decoder to pass or filter other blocks with
+ *   decoded a metadata block.  In a valid FLAC file there will always be
+ *   one STREAMINFO block, followed by zero or more other metadata
+ *   blocks.  These will be supplied by the decoder in the same order as
+ *   they appear in the stream and always before the first audio frame
+ *   (i.e. write callback).  The metadata block that is passed in must not
+ *   be modified, and it doesn't live beyond the callback, so you should
+ *   make a copy of it with FLAC__metadata_object_clone() if you will need
+ *   it elsewhere.  Since metadata blocks can potentially be large, by
+ *   default the decoder only calls the metadata callback for the STREAMINFO
+ *   block; you can instruct the decoder to pass or filter other blocks with
  *   FLAC__stream_decoder_set_metadata_*() calls.
  * - Error callback - This function will be called whenever an error occurs
  *   during decoding.
@@ -442,8 +442,8 @@ FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder,
 FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
 
 /** Set the metadata callback.
- *  The supplied function will be called when the decoder has decoded a
- *  metadata block.  There will always be one STREAMINFO block per stream,
+ *  The supplied function will be called when the decoder has decoded a metadata
+ *  block.  In a valid FLAC file there will always be one STREAMINFO block,
  *  followed by zero or more other metadata blocks.  These will be supplied
  *  by the decoder in the same order as they appear in the stream and always
  *  before the first audio frame (i.e. write callback).  The metadata block

diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h
index 0813d6f..a33530f 100644 (file)
--- a/include/FLAC/stream_encoder.h
+++ b/include/FLAC/stream_encoder.h
@@ -227,7 +227,11 @@ typedef enum {
        /**< An error occurred while writing the stream; usually, the write_callback returned an error. */
 
        FLAC__STREAM_ENCODER_INVALID_METADATA,
-       /**< The metadata input to the encoder is invalid. */
+       /**< The metadata input to the encoder is invalid, in one of the following ways:
+        * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
+        * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
+        * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
+        */
 
        FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING,
        /**< An error occurred while writing the stream; usually, the write_callback returned an error. */
@@ -616,8 +620,22 @@ FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *
  *  Otherwise, the encoder will not modify or free the blocks.  It is up
  *  to the caller to free the metadata blocks after encoding.
  *
- *  The STREAMINFO block is always written and no STREAMINFO block may
- *  occur in the supplied array.
+ * \note
+ * The encoder stores only the \a metadata pointer; the passed-in array
+ * must survive at least until after FLAC__stream_encoder_init() returns.
+ * Do not modify the array or free the blocks until then.
+ *
+ * \note
+ * The STREAMINFO block is always written and no STREAMINFO block may
+ * occur in the supplied array.
+ *
+ * \note
+ * A VORBIS_COMMENT block may be supplied.  The vendor string in it
+ * will be ignored.  libFLAC will use it's own vendor string. libFLAC
+ * will not modify the passed-in VORBIS_COMMENT's vendor string, it
+ * will simply write it's own into the stream.  If no VORBIS_COMMENT
+ * block is present in the \a metadata array, libFLAC will write an
+ * empty one, containing only the vendor string.
  *
  * \default \c NULL, 0
  * \param  encoder     An encoder instance to set.