diff --git a/include/FLAC++/decoder.h b/include/FLAC++/decoder.h index 645ebbe2..cecdd2b6 100644 --- a/include/FLAC++/decoder.h +++ b/include/FLAC++/decoder.h @@ -106,6 +106,8 @@ namespace FLAC { */ class FLACPP_API Stream { public: + /** This class is a wrapper around FLAC__StreamDecoderState. + */ class FLACPP_API State { public: inline State(::FLAC__StreamDecoderState state): state_(state) { } @@ -119,14 +121,13 @@ namespace FLAC { Stream(); virtual ~Stream(); + //@{ /** Call after construction to check the that the object was created * successfully. If not, use get_state() to find out why not. - * - * \{ */ virtual bool is_valid() const; inline operator bool() const { return is_valid(); } - /* \} */ + //@} virtual bool set_md5_checking(bool value); ///< See FLAC__stream_decoder_set_md5_checking() virtual bool set_metadata_respond(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_respond() @@ -249,18 +250,18 @@ namespace FLAC { File(); virtual ~File(); + //@{ /** Initialize the instance; as with the C interface, * init() should be called after construction and 'set' * calls but before any of the 'process' calls. * * See FLAC__stream_decoder_init_FILE() and * FLAC__stream_decoder_init_file(). - * \{ */ ::FLAC__StreamDecoderInitStatus init(FILE *file); ::FLAC__StreamDecoderInitStatus init(const char *filename); ::FLAC__StreamDecoderInitStatus init(const std::string &filename); - /* \} */ + //@} protected: // this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes); diff --git a/include/FLAC++/encoder.h b/include/FLAC++/encoder.h index bdeddc53..3db9bc1e 100644 --- a/include/FLAC++/encoder.h +++ b/include/FLAC++/encoder.h @@ -108,6 +108,8 @@ namespace FLAC { */ class FLACPP_API Stream { public: + /** This class is a wrapper around FLAC__StreamEncoderState. + */ class FLACPP_API State { public: inline State(::FLAC__StreamEncoderState state): state_(state) { } @@ -121,14 +123,14 @@ namespace FLAC { Stream(); virtual ~Stream(); + //@{ /** Call after construction to check the that the object was created * successfully. If not, use get_state() to find out why not. * - * \{ */ virtual bool is_valid() const; inline operator bool() const { return is_valid(); } - /* \} */ + //@} virtual bool set_verify(bool value); ///< See FLAC__stream_encoder_set_verify() virtual bool set_streamable_subset(bool value); ///< See FLAC__stream_encoder_set_streamable_subset() @@ -251,21 +253,21 @@ namespace FLAC { */ class FLACPP_API File: public Stream { public: - /** Initialize the instance; as with the C interface, + File(); + virtual ~File(); + + //@{ + /* Initialize the instance; as with the C interface, * init() should be called after construction and 'set' * calls but before any of the 'process' calls. * * See FLAC__stream_encoder_init_FILE() and * FLAC__stream_encoder_init_file(). - * \{ */ - File(); - virtual ~File(); - /* \} */ - ::FLAC__StreamEncoderInitStatus init(FILE *file); ::FLAC__StreamEncoderInitStatus init(const char *filename); ::FLAC__StreamEncoderInitStatus init(const std::string &filename); + //@} protected: /// See FLAC__StreamEncoderProgressCallback virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate); diff --git a/include/FLAC++/metadata.h b/include/FLAC++/metadata.h index d5b73015..1f8b7bab 100644 --- a/include/FLAC++/metadata.h +++ b/include/FLAC++/metadata.h @@ -100,6 +100,7 @@ namespace FLAC { */ /** Base class for all metadata block types. + * See the \link flacpp_metadata_object overview \endlink for more. */ class FLACPP_API Prototype { protected: @@ -147,7 +148,8 @@ namespace FLAC { virtual ~Prototype(); //@{ - /** Check for equality, performing a deep compare by following pointers. */ + /** Check for equality, performing a deep compare by following pointers. + */ inline bool operator==(const Prototype &) const; inline bool operator==(const ::FLAC__StreamMetadata &) const; inline bool operator==(const ::FLAC__StreamMetadata *) const; @@ -259,7 +261,8 @@ namespace FLAC { /** STREAMINFO metadata block. - * See format specification. + * See the \link flacpp_metadata_object overview \endlink for more, + * and the format specification. */ class FLACPP_API StreamInfo : public Prototype { public: @@ -332,7 +335,8 @@ namespace FLAC { }; /** PADDING metadata block. - * See format specification. + * See the \link flacpp_metadata_object overview \endlink for more, + * and the format specification. */ class FLACPP_API Padding : public Prototype { public: @@ -384,7 +388,8 @@ namespace FLAC { }; /** APPLICATION metadata block. - * See format specification. + * See the \link flacpp_metadata_object overview \endlink for more, + * and the format specification. */ class FLACPP_API Application : public Prototype { public: @@ -442,7 +447,8 @@ namespace FLAC { }; /** SEEKTABLE metadata block. - * See format specification. + * See the \link flacpp_metadata_object overview \endlink for more, + * and the format specification. */ class FLACPP_API SeekTable : public Prototype { public: @@ -507,7 +513,8 @@ namespace FLAC { }; /** VORBIS_COMMENT metadata block. - * See format specification. + * See the \link flacpp_metadata_object overview \endlink for more, + * and the format specification. */ class FLACPP_API VorbisComment : public Prototype { public: @@ -658,7 +665,8 @@ namespace FLAC { }; /** CUESHEET metadata block. - * See format specification. + * See the \link flacpp_metadata_object overview \endlink for more, + * and the format specification. */ class FLACPP_API CueSheet : public Prototype { public: @@ -783,7 +791,8 @@ namespace FLAC { }; /** PICTURE metadata block. - * See format specification. + * See the \link flacpp_metadata_object overview \endlink for more, + * and the format specification. */ class FLACPP_API Picture : public Prototype { public: @@ -862,6 +871,7 @@ namespace FLAC { * This should not be used unless you know what you are doing; * it is currently used only internally to support forward * compatibility of metadata blocks. + * See the \link flacpp_metadata_object overview \endlink for more, */ class FLACPP_API Unknown : public Prototype { public: @@ -931,16 +941,16 @@ namespace FLAC { * \{ */ - FLACPP_API bool get_streaminfo(const char *filename, StreamInfo &streaminfo); //< See FLAC__metadata_get_streaminfo(). + FLACPP_API bool get_streaminfo(const char *filename, StreamInfo &streaminfo); ///< See FLAC__metadata_get_streaminfo(). - FLACPP_API bool get_tags(const char *filename, VorbisComment *&tags); //< See FLAC__metadata_get_tags(). - FLACPP_API bool get_tags(const char *filename, VorbisComment &tags); //< See FLAC__metadata_get_tags(). + FLACPP_API bool get_tags(const char *filename, VorbisComment *&tags); ///< See FLAC__metadata_get_tags(). + FLACPP_API bool get_tags(const char *filename, VorbisComment &tags); ///< See FLAC__metadata_get_tags(). - FLACPP_API bool get_cuesheet(const char *filename, CueSheet *&cuesheet); //! See FLAC__metadata_get_cuesheet(). - FLACPP_API bool get_cuesheet(const char *filename, CueSheet &cuesheet); //! See FLAC__metadata_get_cuesheet(). + FLACPP_API bool get_cuesheet(const char *filename, CueSheet *&cuesheet); ///< See FLAC__metadata_get_cuesheet(). + FLACPP_API bool get_cuesheet(const char *filename, CueSheet &cuesheet); ///< See FLAC__metadata_get_cuesheet(). - FLACPP_API bool get_picture(const char *filename, Picture *&picture, ::FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors); //! See FLAC__metadata_get_picture(). - FLACPP_API bool get_picture(const char *filename, Picture &picture, ::FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors); //! See FLAC__metadata_get_picture(). + FLACPP_API bool get_picture(const char *filename, Picture *&picture, ::FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors); ///< See FLAC__metadata_get_picture(). + FLACPP_API bool get_picture(const char *filename, Picture &picture, ::FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors); ///< See FLAC__metadata_get_picture(). /* \} */ @@ -975,10 +985,14 @@ namespace FLAC { */ /** This class is a wrapper around the FLAC__metadata_simple_iterator - * structures and methods; see ::FLAC__Metadata_SimpleIterator. + * structures and methods; see the + * \link flacpp_metadata_level1 usage guide \endlink and + * ::FLAC__Metadata_SimpleIterator. */ class FLACPP_API SimpleIterator { public: + /** This class is a wrapper around FLAC__Metadata_SimpleIteratorStatus. + */ class FLACPP_API Status { public: inline Status(::FLAC__Metadata_SimpleIteratorStatus status): status_(status) { } @@ -991,20 +1005,20 @@ namespace FLAC { SimpleIterator(); virtual ~SimpleIterator(); - bool init(const char *filename, bool read_only, bool preserve_file_stats); + bool init(const char *filename, bool read_only, bool preserve_file_stats); ///< See FLAC__metadata_simple_iterator_init(). bool is_valid() const; - Status status(); - bool is_writable() const; + Status status(); ///< See FLAC__metadata_simple_iterator_status(). + bool is_writable() const; ///< See FLAC__metadata_simple_iterator_is_writable(). - bool next(); - bool prev(); + bool next(); ///< See FLAC__metadata_simple_iterator_next(). + bool prev(); ///< See FLAC__metadata_simple_iterator_prev(). - ::FLAC__MetadataType get_block_type() const; - Prototype *get_block(); - bool set_block(Prototype *block, bool use_padding = true); - bool insert_block_after(Prototype *block, bool use_padding = true); - bool delete_block(bool use_padding = true); + ::FLAC__MetadataType get_block_type() const; ///< See FLAC__metadata_simple_iterator_get_block_type(). + Prototype *get_block(); ///< See FLAC__metadata_simple_iterator_get_block(). + bool set_block(Prototype *block, bool use_padding = true); ///< See FLAC__metadata_simple_iterator_set_block(). + bool insert_block_after(Prototype *block, bool use_padding = true); ///< See FLAC__metadata_simple_iterator_insert_block_after(). + bool delete_block(bool use_padding = true); ///< See FLAC__metadata_simple_iterator_delete_block(). protected: ::FLAC__Metadata_SimpleIterator *iterator_; @@ -1052,10 +1066,14 @@ namespace FLAC { */ /** This class is a wrapper around the FLAC__metadata_chain - * structures and methods; see ::FLAC__Metadata_Chain. + * structures and methods; see the + * \link flacpp_metadata_level2 usage guide \endlink and + * ::FLAC__Metadata_Chain. */ class FLACPP_API Chain { public: + /** This class is a wrapper around FLAC__Metadata_ChainStatus. + */ class FLACPP_API Status { public: inline Status(::FLAC__Metadata_ChainStatus status): status_(status) { } @@ -1071,19 +1089,19 @@ namespace FLAC { friend class Iterator; bool is_valid() const; - Status status(); + Status status(); ///< See FLAC__metadata_chain_status(). - bool read(const char *filename); - bool read(FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); + bool read(const char *filename); ///< See FLAC__metadata_chain_read(). + bool read(FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); ///< See FLAC__metadata_chain_read_with_callbacks(). - bool check_if_tempfile_needed(bool use_padding); + bool check_if_tempfile_needed(bool use_padding); ///< See FLAC__metadata_chain_check_if_tempfile_needed(). - bool write(bool use_padding = true, bool preserve_file_stats = false); - bool write(bool use_padding, ::FLAC__IOHandle handle, ::FLAC__IOCallbacks callbacks); - bool write(bool use_padding, ::FLAC__IOHandle handle, ::FLAC__IOCallbacks callbacks, ::FLAC__IOHandle temp_handle, ::FLAC__IOCallbacks temp_callbacks); + bool write(bool use_padding = true, bool preserve_file_stats = false); ///< See FLAC__metadata_chain_write(). + bool write(bool use_padding, ::FLAC__IOHandle handle, ::FLAC__IOCallbacks callbacks); ///< See FLAC__metadata_chain_write_with_callbacks(). + bool write(bool use_padding, ::FLAC__IOHandle handle, ::FLAC__IOCallbacks callbacks, ::FLAC__IOHandle temp_handle, ::FLAC__IOCallbacks temp_callbacks); ///< See FLAC__metadata_chain_write_with_callbacks_and_tempfile(). - void merge_padding(); - void sort_padding(); + void merge_padding(); ///< See FLAC__metadata_chain_merge_padding(). + void sort_padding(); ///< See FLAC__metadata_chain_sort_padding(). protected: ::FLAC__Metadata_Chain *chain_; @@ -1091,7 +1109,9 @@ namespace FLAC { }; /** This class is a wrapper around the FLAC__metadata_iterator - * structures and methods; see ::FLAC__Metadata_Iterator. + * structures and methods; see the + * \link flacpp_metadata_level2 usage guide \endlink and + * ::FLAC__Metadata_Iterator. */ class FLACPP_API Iterator { public: @@ -1100,17 +1120,17 @@ namespace FLAC { bool is_valid() const; - void init(Chain &chain); + void init(Chain &chain); ///< See FLAC__metadata_iterator_init(). - bool next(); - bool prev(); + bool next(); ///< See FLAC__metadata_iterator_next(). + bool prev(); ///< See FLAC__metadata_iterator_prev(). - ::FLAC__MetadataType get_block_type() const; - Prototype *get_block(); - bool set_block(Prototype *block); - bool delete_block(bool replace_with_padding); - bool insert_block_before(Prototype *block); - bool insert_block_after(Prototype *block); + ::FLAC__MetadataType get_block_type() const; ///< See FLAC__metadata_iterator_get_block_type(). + Prototype *get_block(); ///< See FLAC__metadata_iterator_get_block(). + bool set_block(Prototype *block); ///< See FLAC__metadata_iterator_set_block(). + bool delete_block(bool replace_with_padding); ///< See FLAC__metadata_iterator_delete_block(). + bool insert_block_before(Prototype *block); ///< See FLAC__metadata_iterator_insert_block_before(). + bool insert_block_after(Prototype *block); ///< See FLAC__metadata_iterator_insert_block_after(). protected: ::FLAC__Metadata_Iterator *iterator_; diff --git a/include/FLAC/all.h b/include/FLAC/all.h index 40180512..b1f29b36 100644 --- a/include/FLAC/all.h +++ b/include/FLAC/all.h @@ -59,7 +59,7 @@ * describing the components of FLAC streams, and functions for * encoding and decoding streams, as well as manipulating FLAC * metadata in files. The public include files will be installed - * in your include area as /FLAC/... + * in your include area (for example /usr/include/FLAC/...). * * By writing a little code and linking against libFLAC, it is * relatively easy to add FLAC support to another program. The @@ -94,8 +94,8 @@ * equivalent. For the most part, they share the same usage as * their counterparts in libFLAC, and the FLAC C API documentation * can be used as a supplement. The public include files - * for the C++ API will be installed in your include area as - * /FLAC++/... + * for the C++ API will be installed in your include area (for + * example /usr/include/FLAC++/...). * * There is also a libOggFLAC++ library, which provides classes * for encoding to and decoding from FLAC streams in an Ogg container. diff --git a/include/FLAC/callback.h b/include/FLAC/callback.h index 54133e6c..b228c0f0 100644 --- a/include/FLAC/callback.h +++ b/include/FLAC/callback.h @@ -82,6 +82,9 @@ extern "C" { #endif +/** This is the opaque handle type used by the callbacks. Typically + * this is a \c FILE* or address of a file descriptor. + */ typedef void* FLAC__IOHandle; /** Signature for the read callback. diff --git a/include/FLAC/format.h b/include/FLAC/format.h index fbfa7a26..b0b93c01 100644 --- a/include/FLAC/format.h +++ b/include/FLAC/format.h @@ -338,10 +338,10 @@ extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; /**< == 1 (bit) */ extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */ extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */ -extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */ -extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */ -extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */ -extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */ +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /**< = 0x00 */ +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /**< = 0x02 */ +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /**< = 0x10 */ +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /**< = 0x40 */ /*****************************************************************************/ @@ -641,7 +641,7 @@ typedef struct { /**< The track number. */ char isrc[13]; - /**< Track ISRC. This is a 12-digit alphanumeric code plus a trailing '\0' */ + /**< Track ISRC. This is a 12-digit alphanumeric code plus a trailing \c NUL byte */ unsigned type:1; /**< The track type: 0 for audio, 1 for non-audio. */ @@ -891,7 +891,8 @@ FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__ * FLAC__format_vorbiscomment_entry_name_is_legal() and * FLAC__format_vorbiscomment_entry_value_is_legal() respectively. * - * \param value A string to be checked. + * \param entry An entry to be checked. + * \param length The length of \a entry in bytes. * \assert * \code value != NULL \endcode * \retval FLAC__bool diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h index 13265e28..2aa9fb89 100644 --- a/include/FLAC/metadata.h +++ b/include/FLAC/metadata.h @@ -1404,7 +1404,7 @@ FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_point * second at sample \a samples, then 2*\a samples, and * so on. As long as \a samples and \a total_samples * are greater than \c 0, there will always be at least - * one seekpoint at sample \0. + * one seekpoint at sample \c 0. * \param total_samples The total number of samples to be encoded; * the seekpoints will be spaced * \a samples samples apart. @@ -2031,7 +2031,7 @@ FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata * See the format specification for limits on the contents of the * PICTURE block. * - * \param picture A pointer to existing PICTURE block to be checked. + * \param object A pointer to existing PICTURE block to be checked. * \param violation Address of a pointer to a string. If there is a * violation, a pointer to a string explanation of the * violation will be returned here. \a violation may be diff --git a/include/OggFLAC++/decoder.h b/include/OggFLAC++/decoder.h index 308e8953..e882e297 100644 --- a/include/OggFLAC++/decoder.h +++ b/include/OggFLAC++/decoder.h @@ -138,6 +138,8 @@ namespace OggFLAC { */ class OggFLACPP_API Stream: public FLAC::Decoder::Stream { public: + /** This class is a wrapper around OggFLAC__StreamDecoderState. + */ class OggFLACPP_API State { public: inline State(::OggFLAC__StreamDecoderState state): state_(state) { } @@ -208,7 +210,7 @@ namespace OggFLAC { * \brief * This class wraps the ::OggFLAC__FileDecoder. * - * See the \link oggflac_file_decoder libOggFLAC file decoder module \endlink + * See the \link oggflac_stream_decoder libOggFLAC stream decoder module \endlink * for basic usage. * * \{ @@ -236,18 +238,18 @@ namespace OggFLAC { File(); virtual ~File(); + //@{ /** Initialize the instance; as with the C interface, * init() should be called after construction and 'set' * calls but before any of the 'process' calls. * * See OggFLAC__stream_decoder_init_FILE() and * OggFLAC__stream_decoder_init_file(). - * \{ */ ::FLAC__StreamDecoderInitStatus init(FILE *file); ::FLAC__StreamDecoderInitStatus init(const char *filename); ::FLAC__StreamDecoderInitStatus init(const std::string &filename); - /* \} */ + //@} protected: // this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes); diff --git a/include/OggFLAC++/encoder.h b/include/OggFLAC++/encoder.h index f2d4f946..ca48bafd 100644 --- a/include/OggFLAC++/encoder.h +++ b/include/OggFLAC++/encoder.h @@ -141,6 +141,8 @@ namespace OggFLAC { */ class OggFLACPP_API Stream: public FLAC::Encoder::Stream { public: + /** This class is a wrapper around OggFLAC__StreamEncoderState. + */ class OggFLACPP_API State { public: inline State(::OggFLAC__StreamEncoderState state): state_(state) { } @@ -233,7 +235,7 @@ namespace OggFLAC { * \brief * This class wraps the ::OggFLAC__FileEncoder. * - * See the \link oggflac_file_encoder libOggFLAC file encoder module \endlink + * See the \link oggflac_stream_encoder libOggFLAC stream encoder module \endlink * for basic usage. * * \{ @@ -259,21 +261,21 @@ namespace OggFLAC { */ class OggFLACPP_API File: public Stream { public: + File(); + virtual ~File(); + + //@{ /** Initialize the instance; as with the C interface, * init() should be called after construction and 'set' * calls but before any of the 'process' calls. * * See OggFLAC__stream_encoder_init_FILE() and * OggFLAC__stream_encoder_init_file(). - * \{ */ - File(); - virtual ~File(); - /* \} */ - ::FLAC__StreamEncoderInitStatus init(FILE *file); ::FLAC__StreamEncoderInitStatus init(const char *filename); ::FLAC__StreamEncoderInitStatus init(const std::string &filename); + //@} protected: /// See FLAC__StreamEncoderProgressCallback virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);