From: Josh Coalson Date: Mon, 20 Nov 2006 05:30:25 +0000 (+0000) Subject: minor comments X-Git-Tag: 1.2.0~262 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=2378fb18889754f235e3e20d1f903d351e4b3a2d;p=platform%2Fupstream%2Fflac.git minor comments --- diff --git a/include/FLAC++/decoder.h b/include/FLAC++/decoder.h index cb3d38c..78730db 100644 --- a/include/FLAC++/decoder.h +++ b/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() diff --git a/include/FLAC++/encoder.h b/include/FLAC++/encoder.h index 67f2a13..0752ccd 100644 --- a/include/FLAC++/encoder.h +++ b/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() diff --git a/include/FLAC++/metadata.h b/include/FLAC++/metadata.h index d26a92f..f8bb640 100644 --- a/include/FLAC++/metadata.h +++ b/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. */ diff --git a/include/FLAC/all.h b/include/FLAC/all.h index 4b493fd..efe67dc 100644 --- a/include/FLAC/all.h +++ b/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 * Xiph's BSD license. * @@ -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(). * diff --git a/include/FLAC/export.h b/include/FLAC/export.h index 8d9e793..7a79317 100644 --- a/include/FLAC/export.h +++ b/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. * * \{ */ diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h index f6baa70..f347268 100644 --- a/include/FLAC/metadata.h +++ b/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 diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h index 03d0027..e28315c 100644 --- a/include/FLAC/stream_decoder.h +++ b/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. diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h index 4a8ce34..c5f0c50 100644 --- a/include/FLAC/stream_encoder.h +++ b/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: