Commit 20ad84aa authored by Josh Coalson's avatar Josh Coalson
Browse files

more doxygen comments

parent e401faa9
......@@ -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);
......
......@@ -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);
......
......@@ -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 <A HREF="../format.html#metadata_block_streaminfo">format specification</A>.
* See the \link flacpp_metadata_object overview \endlink for more,
* and the <A HREF="../format.html#metadata_block_streaminfo">format specification</A>.
*/
class FLACPP_API StreamInfo : public Prototype {
public:
......@@ -332,7 +335,8 @@ namespace FLAC {
};
/** PADDING metadata block.
* See <A HREF="../format.html#metadata_block_padding">format specification</A>.
* See the \link flacpp_metadata_object overview \endlink for more,
* and the <A HREF="../format.html#metadata_block_padding">format specification</A>.
*/
class FLACPP_API Padding : public Prototype {
public:
......@@ -384,7 +388,8 @@ namespace FLAC {
};
/** APPLICATION metadata block.
* See <A HREF="../format.html#metadata_block_application">format specification</A>.
* See the \link flacpp_metadata_object overview \endlink for more,
* and the <A HREF="../format.html#metadata_block_application">format specification</A>.
*/
class FLACPP_API Application : public Prototype {
public:
......@@ -442,7 +447,8 @@ namespace FLAC {
};
/** SEEKTABLE metadata block.
* See <A HREF="../format.html#metadata_block_seektable">format specification</A>.
* See the \link flacpp_metadata_object overview \endlink for more,
* and the <A HREF="../format.html#metadata_block_seektable">format specification</A>.
*/
class FLACPP_API SeekTable : public Prototype {
public:
......@@ -507,7 +513,8 @@ namespace FLAC {
};
/** VORBIS_COMMENT metadata block.
* See <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>.
* See the \link flacpp_metadata_object overview \endlink for more,
* and the <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>.
*/
class FLACPP_API VorbisComment : public Prototype {
public:
......@@ -658,7 +665,8 @@ namespace FLAC {
};
/** CUESHEET metadata block.
* See <A HREF="../format.html#metadata_block_cuesheet">format specification</A>.
* See the \link flacpp_metadata_object overview \endlink for more,
* and the <A HREF="../format.html#metadata_block_cuesheet">format specification</A>.
*/
class FLACPP_API CueSheet : public Prototype {
public:
......@@ -783,7 +791,8 @@ namespace FLAC {
};
/** PICTURE metadata block.
* See <A HREF="../format.html#metadata_block_picture">format specification</A>.
* See the \link flacpp_metadata_object overview \endlink for more,
* and the <A HREF="../format.html#metadata_block_picture">format specification</A>.
*/
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_;
......
......@@ -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 <include>/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
* <include>/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.
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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);
......
......@@ -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);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment