From 402da70fcd12d1066b856e62e4837e1532ee942e Mon Sep 17 00:00:00 2001 From: Josh Coalson Date: Wed, 21 Aug 2002 03:40:11 +0000 Subject: [PATCH] more doxygen docs --- include/FLAC++/all.h | 2 +- include/FLAC++/decoder.h | 58 +++++++++++++++++++-------------------------- include/FLAC++/encoder.h | 54 +++++++++++++++-------------------------- include/FLAC++/metadata.h | 13 +++++----- include/OggFLAC++/decoder.h | 41 ++++++++++++-------------------- include/OggFLAC++/encoder.h | 37 +++++++++++------------------ 6 files changed, 80 insertions(+), 125 deletions(-) diff --git a/include/FLAC++/all.h b/include/FLAC++/all.h index 72820ad..88ce27d 100644 --- a/include/FLAC++/all.h +++ b/include/FLAC++/all.h @@ -33,7 +33,7 @@ * Note that Doxygen currently has some quirks (bugs?) in the way * it deals with some member groups and C++ constructs. You will find * some document entries in the wrong place under [NOHEADER] sections. - * Hopefully this is not too annoying. + * Hopefully this is not too distracting. */ #endif diff --git a/include/FLAC++/decoder.h b/include/FLAC++/decoder.h index 37d114f..52316a0 100644 --- a/include/FLAC++/decoder.h +++ b/include/FLAC++/decoder.h @@ -24,18 +24,11 @@ #include "FLAC/seekable_stream_decoder.h" #include "FLAC/stream_decoder.h" -// =============================================================== -// -// Full documentation for the decoder interfaces can be found -// in the C layer in include/FLAC/ *_decoder.h -// -// =============================================================== - /** \file include/FLAC++/decoder.h * * \brief - * This file contains the classes which implement the various + * This module contains the classes which implement the various * decoders. * * See the detailed documentation in the @@ -46,9 +39,17 @@ * \ingroup flacpp * * \brief - * Brief XXX. + * This module describes the three decoder layers provided by libFLAC++. + * + * The libFLAC++ decoder classes are object wrappers around their + * counterparts in libFLAC. All three decoding layers available in + * libFLAC are also provided here. The interface is very similar; + * make sure to read the \link flac_decoder libFLAC decoder module \endlink. * - * Detailed decoder XXX. + * The only real difference here is that instead of passing in C function + * pointers for callbacks, you inherit from the decoder class and provide + * implementations for the callbacks in the derived class; because of this + * there is no need for a 'client_data' property. */ namespace FLAC { @@ -56,16 +57,6 @@ namespace FLAC { // ============================================================ // - // The only real difference here is that instead of passing - // in C function pointers for callbacks, you inherit from the - // decoder class and provide implementations for the callbacks - // in the derived class; because of this there is no need for - // a 'client_data' property. - // - // ============================================================ - - // ============================================================ - // // Equivalent: FLAC__StreamDecoder // // ============================================================ @@ -74,14 +65,14 @@ namespace FLAC { * \ingroup flacpp_decoder * * \brief - * Brief XXX. + * This class wraps the ::FLAC__StreamDecoder. * - * Detailed stream decoder XXX. + * See the \link flac_stream_decoder libFLAC stream decoder module \endlink. * * \{ */ - /** stream decoder XXX. + /** This class wraps the ::FLAC__StreamDecoder. */ class Stream { public: @@ -114,9 +105,10 @@ namespace FLAC { unsigned get_sample_rate() const; unsigned get_blocksize() const; - // Initialize the instance; as with the C interface, - // init() should be called after construction and 'set' - // calls but before any of the 'process' calls. + /** Initialize the instance; as with the C interface, + * init() should be called after construction and 'set' + * calls but before any of the 'process' calls. + */ State init(); void finish(); @@ -158,14 +150,14 @@ namespace FLAC { * \ingroup flacpp_decoder * * \brief - * Brief XXX. + * This class wraps the ::FLAC__SeekableStreamDecoder. * - * Detailed seekable stream decoder XXX. + * See the \link flac_seekable_stream_decoder libFLAC seekable stream decoder module \endlink. * * \{ */ - /** seekable stream decoder XXX. + /** This class wraps the ::FLAC__SeekableStreamDecoder. */ class SeekableStream { public: @@ -252,14 +244,14 @@ namespace FLAC { * \ingroup flacpp_decoder * * \brief - * Brief XXX. + * This class wraps the ::FLAC__FileDecoder. * - * Detailed file decoder XXX. + * See the \link flac_file_decoder libFLAC file decoder module \endlink. * * \{ */ - /** file decoder XXX. + /** This class wraps the ::FLAC__FileDecoder. */ class File { public: @@ -279,7 +271,7 @@ namespace FLAC { inline operator bool() const { return is_valid(); } bool set_md5_checking(bool value); - bool set_filename(const char *value); // 'value' may not be 0; use "-" for stdin + bool set_filename(const char *value); //!< 'value' may not be \c NULL; use "-" for stdin bool set_metadata_respond(::FLAC__MetadataType type); bool set_metadata_respond_application(const FLAC__byte id[4]); bool set_metadata_respond_all(); diff --git a/include/FLAC++/encoder.h b/include/FLAC++/encoder.h index 9af6569..90aafad 100644 --- a/include/FLAC++/encoder.h +++ b/include/FLAC++/encoder.h @@ -25,13 +25,6 @@ #include "FLAC/stream_encoder.h" #include "decoder.h" -// =============================================================== -// -// Full documentation for the encoder interfaces can be found -// in the C layer in include/FLAC/ *_encoder.h -// -// =============================================================== - /** \file include/FLAC++/encoder.h * @@ -47,9 +40,17 @@ * \ingroup flacpp * * \brief - * Brief XXX. + * This module describes the three encoder layers provided by libFLAC++. + * + * The libFLAC++ encoder classes are object wrappers around their + * counterparts in libFLAC. All three encoding layers available in + * libFLAC are also provided here. The interface is very similar; + * make sure to read the \link flac_encoder libFLAC encoder module \endlink. * - * Detailed encoder XXX. + * The only real difference here is that instead of passing in C function + * pointers for callbacks, you inherit from the encoder class and provide + * implementations for the callbacks in the derived class; because of this + * there is no need for a 'client_data' property. */ namespace FLAC { @@ -59,28 +60,20 @@ namespace FLAC { // // Equivalent: FLAC__StreamEncoder // - // ---------------------------------------------------------- - // - // The only real difference here is that instead of passing - // in C function pointers for callbacks, you inherit from the - // encoder class and provide implementations for the callbacks - // in the derived class; because of this there is no need for - // a 'client_data' property. - // // ============================================================ /** \defgroup flacpp_stream_encoder FLAC++/encoder.h: stream encoder class * \ingroup flacpp_encoder * * \brief - * Brief XXX. + * This class wraps the ::FLAC__StreamEncoder. * - * Detailed stream encoder XXX. + * See the \link flac_stream_encoder libFLAC stream encoder module \endlink. * * \{ */ - /** stream encoder XXX. + /** This class wraps the ::FLAC__StreamEncoder. */ class Stream { public: @@ -139,9 +132,6 @@ namespace FLAC { unsigned get_rice_parameter_search_dist() const; FLAC__uint64 get_total_samples_estimate() const; - // Initialize the instance; as with the C interface, - // init() should be called after construction and 'set' - // calls but before any of the 'process' calls. State init(); void finish(); @@ -168,14 +158,14 @@ namespace FLAC { * \ingroup flacpp_encoder * * \brief - * Brief XXX. + * This class wraps the ::FLAC__SeekableStreamEncoder. * - * Detailed seekable stream encoder XXX. + * See the \link flac_seekable_stream_encoder libFLAC seekable stream encoder module \endlink. * * \{ */ - /** seekable stream encoder XXX. + /** This class wraps the ::FLAC__SeekableStreamEncoder. */ class SeekableStream { public: @@ -235,9 +225,6 @@ namespace FLAC { unsigned get_rice_parameter_search_dist() const; FLAC__uint64 get_total_samples_estimate() const; - // Initialize the instance; as with the C interface, - // init() should be called after construction and 'set' - // calls but before any of the 'process' calls. State init(); void finish(); @@ -264,14 +251,14 @@ namespace FLAC { * \ingroup flacpp_encoder * * \brief - * Brief XXX. + * This class wraps the ::FLAC__FileEncoder. * - * Detailed file encoder XXX. + * See the \link flac_file_encoder libFLAC file encoder module \endlink. * * \{ */ - /** file encoder XXX. + /** This class wraps the ::FLAC__FileEncoder. */ class File { public: @@ -333,9 +320,6 @@ namespace FLAC { unsigned get_rice_parameter_search_dist() const; FLAC__uint64 get_total_samples_estimate() const; - // Initialize the instance; as with the C interface, - // init() should be called after construction and 'set' - // calls but before any of the 'process' calls. State init(); void finish(); diff --git a/include/FLAC++/metadata.h b/include/FLAC++/metadata.h index 430e35c..842b8e8 100644 --- a/include/FLAC++/metadata.h +++ b/include/FLAC++/metadata.h @@ -624,12 +624,11 @@ namespace FLAC { * \{ */ - /** XXX class SimpleIterator + /** This class is a wrapper around the FLAC__metadata_simple_iterator + * structures and methods; see ::FLAC__Metadata_SimpleIterator. */ class SimpleIterator { public: - /** XXX class SimpleIterator::Status - */ class Status { public: inline Status(::FLAC__Metadata_SimpleIteratorStatus status): status_(status) { } @@ -702,12 +701,11 @@ namespace FLAC { * \{ */ - /** XXX class Chain + /** This class is a wrapper around the FLAC__metadata_chain + * structures and methods; see ::FLAC__Metadata_Chain. */ class Chain { public: - /** XXX class Chain::Status - */ class Status { public: inline Status(::FLAC__Metadata_ChainStatus status): status_(status) { } @@ -736,7 +734,8 @@ namespace FLAC { virtual void clear(); }; - /** XXX class Iterator + /** This class is a wrapper around the FLAC__metadata_iterator + * structures and methods; see ::FLAC__Metadata_Iterator. */ class Iterator { public: diff --git a/include/OggFLAC++/decoder.h b/include/OggFLAC++/decoder.h index 21a7e41..000f015 100644 --- a/include/OggFLAC++/decoder.h +++ b/include/OggFLAC++/decoder.h @@ -24,18 +24,11 @@ // we only need this for the state abstraction really... #include "FLAC++/decoder.h" -// =============================================================== -// -// Full documentation for the decoder interfaces can be found -// in the C layer in include/OggFLAC/ *_decoder.h -// -// =============================================================== - /** \file include/OggFLAC++/decoder.h * * \brief - * This file contains the classes which implement the various + * This module contains the classes which implement the various * decoders. * * See the detailed documentation in the @@ -46,9 +39,17 @@ * \ingroup oggflacpp * * \brief - * Brief XXX. + * This module describes the decoder layers provided by libOggFLAC++. + * + * The libOggFLAC++ decoder classes are object wrappers around their + * counterparts in libOggFLAC. Only the stream decoding layer in + * libOggFLAC provided here. The interface is very similar; + * make sure to read the \link oggflac_decoder libOggFLAC decoder module \endlink. * - * Detailed decoder XXX. + * The only real difference here is that instead of passing in C function + * pointers for callbacks, you inherit from the decoder class and provide + * implementations for the callbacks in the derived class; because of this + * there is no need for a 'client_data' property. */ namespace OggFLAC { @@ -56,16 +57,6 @@ namespace OggFLAC { // ============================================================ // - // The only real difference here is that instead of passing - // in C function pointers for callbacks, you inherit from - // stream and provide implementations for the callbacks in - // the derived class; because of this there is no need for a - // 'client_data' property. - // - // ============================================================ - - // ============================================================ - // // Equivalent: OggFLAC__StreamDecoder // // ============================================================ @@ -74,13 +65,14 @@ namespace OggFLAC { * \ingroup oggflacpp_decoder * * \brief - * Brief XXX. + * This class wraps the ::OggFLAC__StreamDecoder. + * + * See the \link oggflac_stream_decoder libOggFLAC stream decoder module \endlink. * - * Detailed stream decoder XXX. * \{ */ - /** stream decoder XXX. + /** This class wraps the ::OggFLAC__StreamDecoder. */ class Stream { public: @@ -114,9 +106,6 @@ namespace OggFLAC { unsigned get_sample_rate() const; unsigned get_blocksize() const; - // Initialize the instance; as with the C interface, - // init() should be called after construction and 'set' - // calls but before any of the 'process' calls. State init(); void finish(); diff --git a/include/OggFLAC++/encoder.h b/include/OggFLAC++/encoder.h index c9ba293..632ba8d 100644 --- a/include/OggFLAC++/encoder.h +++ b/include/OggFLAC++/encoder.h @@ -26,13 +26,6 @@ #include "FLAC++/decoder.h" #include "FLAC++/encoder.h" -// =============================================================== -// -// Full documentation for the encoder interfaces can be found -// in the C layer in include/OggFLAC/ *_encoder.h -// -// =============================================================== - /** \file include/OggFLAC++/encoder.h * @@ -48,9 +41,17 @@ * \ingroup oggflacpp * * \brief - * Brief XXX. + * This module describes the encoder layers provided by libOggFLAC++. + * + * The libOggFLAC++ encoder classes are object wrappers around their + * counterparts in libOggFLAC. Only the stream encoding layer in + * libOggFLAC is provided here. The interface is very similar; + * make sure to read the \link oggflac_encoder libOggFLAC encoder module \endlink. * - * Detailed encoder XXX. + * The only real difference here is that instead of passing in C function + * pointers for callbacks, you inherit from the encoder class and provide + * implementations for the callbacks in the derived class; because of this + * there is no need for a 'client_data' property. */ namespace OggFLAC { @@ -60,27 +61,20 @@ namespace OggFLAC { // // Equivalent: OggFLAC__StreamEncoder // - // ---------------------------------------------------------- - // - // The only real difference here is that instead of passing - // in C function pointers for callbacks, you inherit from - // stream and provide implementations for the callbacks in - // the derived class; because of this there is no need for a - // 'client_data' property. - // // ============================================================ /** \defgroup oggflacpp_stream_encoder OggFLAC++/encoder.h: stream encoder class * \ingroup oggflacpp_encoder * * \brief - * Brief XXX. + * This class wraps the ::OggFLAC__StreamEncoder. + * + * See the \link oggflac_stream_encoder libOggFLAC stream encoder module \endlink. * - * Detailed stream encoder XXX. * \{ */ - /** stream encoder XXX. + /** This class wraps the ::OggFLAC__StreamEncoder. */ class Stream { public: @@ -140,9 +134,6 @@ namespace OggFLAC { unsigned get_rice_parameter_search_dist() const; FLAC__uint64 get_total_samples_estimate() const; - // Initialize the instance; as with the C interface, - // init() should be called after construction and 'set' - // calls but before any of the 'process' calls. State init(); void finish(); -- 2.7.4