minor comments

include/FLAC++/decoder.h

@@ -67,7 +67,7 @@
  *
  * Second, there are two stream decoder classes.  FLAC::Decoder::Stream
  * is used for the same cases that FLAC__stream_decoder_init_stream() /
- * FLAC__stream_decoder_init_ogg_stream() is used, and FLAC::Decoder::File
+ * FLAC__stream_decoder_init_ogg_stream() are used, and FLAC::Decoder::File
  * is used for the same cases that
  * FLAC__stream_decoder_init_FILE() and FLAC__stream_decoder_init_file() /
  * FLAC__stream_decoder_init_ogg_FILE() and FLAC__stream_decoder_init_ogg_file()

include/FLAC++/encoder.h

@@ -68,7 +68,7 @@
  *
  * Second, there are two stream encoder classes.  FLAC::Encoder::Stream
  * is used for the same cases that FLAC__stream_encoder_init_stream() /
- * FLAC__stream_encoder_init_ogg_stream() is used, and FLAC::Encoder::File
+ * FLAC__stream_encoder_init_ogg_stream() are used, and FLAC::Encoder::File
  * is used for the same cases that
  * FLAC__stream_encoder_init_FILE() and FLAC__stream_encoder_init_file() /
  * FLAC__stream_encoder_init_ogg_FILE() and FLAC__stream_encoder_init_ogg_file()

include/FLAC++/metadata.h

@@ -64,8 +64,10 @@
  *
  *  The behavior closely mimics the C layer interface; be sure to read
  *  the detailed description of the
- *  \link flac_metadata C metadata module \endlink.  Note that the
- *  metadata API currently does not support Ogg FLAC files.
+ *  \link flac_metadata C metadata module \endlink.  Note that like the
+ *  C layer, currently only the Chain interface (level 2) supports Ogg
+ *  FLAC files, and it is read-only i.e. no writing back changed
+ *  metadata to file.
  */
 
 

include/FLAC/all.h

@@ -81,8 +81,8 @@
  * global variables and should be thread-safe.
  *
  * libFLAC also supports encoding to and decoding from Ogg FLAC.
- * However the metadata editing interfaces currently work only for
- * native FLAC files.
+ * However the metadata editing interfaces currently have limited
+ * read-only support for Ogg FLAC files.
  *
  * \section cpp_api FLAC C++ API
  *
@@ -95,10 +95,6 @@
  * for the C++ API will be installed in your include area (for
  * example /usr/include/FLAC++/...).
  *
- * libFLAC++ also supports encoding to and decoding from Ogg FLAC.
- * However the metadata editing interfaces currently work only for
- * native FLAC files.
- *
  * libFLAC++ is also licensed under
  * <A HREF="../license.html">Xiph's BSD license</A>.
  *
@@ -136,7 +132,8 @@
  * - The decoder is independent of the encoder.  The encoder uses the
  *   decoder because of the verify feature, but this can be removed if
  *   not needed.
- * - The metadata interface requires the stream decoder.
+ * - Parts of the metadata interface require the stream decoder (but not
+ *   the encoder).
  * - Ogg support is selectable through the compile time macro
  *   \c FLAC__HAS_OGG.
  *
@@ -201,7 +198,7 @@
  *
  * Instead of creating an encoder or decoder of a certain layer, now the
  * client will always create a FLAC__StreamEncoder or
- * FLAC__StreamDecoder.  The different layers are differentiated by the
+ * FLAC__StreamDecoder.  The old layers are now differentiated by the
  * initialization function.  For example, for the decoder,
  * FLAC__stream_decoder_init() has been replaced by
  * FLAC__stream_decoder_init_stream().  This init function takes
@@ -308,8 +305,8 @@
  * The encoder now has a new setting:
  * FLAC__stream_encoder_set_apodization().  This is for setting the
  * method used to window the data before LPC analysis.  You only need to
- * add a call to this function if the default is not   There are also
- * two new convenience functions that may be useful:
+ * add a call to this function if the default is not suitable.   There
+ * are also two new convenience functions that may be useful:
  * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
  * FLAC__metadata_get_cuesheet().
  *

include/FLAC/export.h

@@ -45,9 +45,8 @@
  *  \ingroup flac
  *
  *  \brief
- *  This module contains structure definitions for the representation
- *  of FLAC format components in memory.  These are the basic
- *  structures used by the rest of the interfaces.
+ *  This module contains #defines and symbols for exporting function
+ *  calls, and providing version information and compiled-in features.
  *
  * \{
  */

include/FLAC/metadata.h

@@ -100,7 +100,8 @@
  *
  *  All levels access files via their filenames.  In addition, level 2
  *  has additional alternative read and write functions that take an I/O
- *  handle and callbacks, for times when access by filename is not possible.
+ *  handle and callbacks, for situations where access by filename is not
+ *  possible.
  *
  *  In addition to the three interfaces, this module defines functions for
  *  creating and manipulating various metadata objects in memory.  As we see

include/FLAC/stream_decoder.h

@@ -51,7 +51,7 @@ extern "C" {
  *  \link flac_stream_decoder stream decoder \endlink module.
  */
 
-/** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces
+/** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
  *  \ingroup flac
  *
  *  \brief
@@ -112,8 +112,8 @@ extern "C" {
  * seeking) are optional, depending on the capabilities of the input.
  *
  * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
- * or FLAC__stream_decoder_init_file().  Then you must only supply a
- * filename or open \c FILE* and fewer callbacks; the decoder will handle
+ * or FLAC__stream_decoder_init_file().  Then you must only supply an open
+ * \c FILE* or filename and fewer callbacks; the decoder will handle
  * the other callbacks internally.
  *
  * There are three similarly-named init functions for decoding from Ogg
@@ -168,13 +168,13 @@ extern "C" {
  * explicitly which blocks to parse and return via the metadata_callback
  * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
  * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
- * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify which
- * blocks to return.  Remember that some metadata blocks can be big so
- * filtering out the ones you don't use can reduce the memory requirements
- * of the decoder.  Also note the special forms
- * FLAC__stream_decoder_set_metadata_respond_application(id) and
- * FLAC__stream_decoder_set_metadata_ignore_application(id) for filtering APPLICATION
- * blocks based on the application ID.
+ * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
+ * which blocks to return.  Remember that metadata blocks can potentially
+ * be big (for example, cover art) so filtering out the ones you don't
+ * use can reduce the memory requirements of the decoder.  Also note the
+ * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
+ * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
+ * filtering APPLICATION blocks based on the application ID.
  *
  * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
  * they still can legally be filtered from the metadata_callback.

include/FLAC/stream_encoder.h

@@ -52,7 +52,7 @@ extern "C" {
  *  \link flac_stream_encoder stream encoder \endlink module.
  */
 
-/** \defgroup flac_encoder FLAC/ *_encoder.h: encoder interfaces
+/** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
  *  \ingroup flac
  *
  *  \brief
@@ -163,8 +163,8 @@ extern "C" {
  * The call to FLAC__stream_encoder_init_*() currently will also immediately
  * call the write callback several times, once with the \c fLaC signature,
  * and once for each encoded metadata block.  Note that for Ogg FLAC
- * encoding you will usually get twice the number of callbacks than with
- * native FLAC, one for the Ogg page header and one for the page body.
+ * encoding you will usually get at least twice the number of callbacks than
+ * with native FLAC, one for the Ogg page header and one for the page body.
  *
  * After initializing the instance, the client may feed audio data to the
  * encoder in one of two ways: