more doxygen docs

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

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,24 +39,22 @@
  *  \ingroup flacpp
  *
  *  \brief
- *  Brief XXX.
+ *  This module describes the three decoder layers provided by libFLAC++.
  *
- * Detailed decoder XXX.
+ * 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.
+ *
+ * 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 {
 	namespace Decoder {
 
-		// ============================================================
-		//
-		//  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,
+			/** Initialize the instance; as with the C interface,
-			// init() should be called after construction and 'set'
+			 *  init() should be called after construction and 'set'
-			// calls but before any of the 'process' calls.
+			 *  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();

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++.
  *
- * Detailed encoder XXX.
+ * 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.
+ *
+ * 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();

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:

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,24 +39,22 @@
  *  \ingroup oggflacpp
  *
  *  \brief
- *  Brief XXX.
+ *  This module describes the decoder layers provided by libOggFLAC++.
  *
- * Detailed decoder XXX.
+ * 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.
+ *
+ * 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 {
 	namespace Decoder {
 
-		// ============================================================
-		//
-		//  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();

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++.
  *
- * Detailed encoder XXX.
+ * 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.
+ *
+ * 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();