more doxygen docs

[platform/upstream/flac.git] / include / OggFLAC++ / decoder.h

diff --git a/include/OggFLAC++/decoder.h b/include/OggFLAC++/decoder.h
index 21a7e41..000f015 100644 (file)
--- 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();