diff --git a/Doxyfile.cmake b/Doxyfile.cmake index 3c955f2a7..2f4b8b38f 100644 --- a/Doxyfile.cmake +++ b/Doxyfile.cmake @@ -12,7 +12,6 @@ OUTPUT_DIRECTORY = doc CREATE_SUBDIRS = NO ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English -OUTPUT_TEXT_DIRECTION = None BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = "The $name class" \ @@ -239,7 +238,6 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain LATEX_TIMESTAMP = NO LATEX_EMOJI_DIRECTORY = @@ -252,7 +250,6 @@ COMPACT_RTF = NO RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = -RTF_SOURCE_CODE = NO #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- @@ -273,7 +270,6 @@ XML_NS_MEMB_FILE_SCOPE = NO #--------------------------------------------------------------------------- GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- @@ -309,7 +305,6 @@ EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -CLASS_DIAGRAMS = YES DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES diff --git a/bindings/README b/bindings/README index bfbd44ae0..777910a81 100644 --- a/bindings/README +++ b/bindings/README @@ -2,5 +2,4 @@ There are a few other people that have done bindings externally that I have been made aware of. I have not personally reviewed these bindings, but I'm listing them here so that those who find them useful are able to find them: -http://developer.kde.org/~wheeler/taglib.html#bindings - +https://taglib.org/#language-bindings diff --git a/bindings/c/tag_c.h b/bindings/c/tag_c.h index 641369911..44c855d62 100644 --- a/bindings/c/tag_c.h +++ b/bindings/c/tag_c.h @@ -164,7 +164,7 @@ TAGLIB_C_EXPORT TagLib_File *taglib_file_new_iostream(TagLib_IOStream *stream); TAGLIB_C_EXPORT void taglib_file_free(TagLib_File *file); /*! - * Returns true if the file is open and readable and valid information for + * Returns \c true if the file is open and readable and valid information for * the Tag and / or AudioProperties was found. */ diff --git a/taglib/ape/apefile.h b/taglib/ape/apefile.h index 134e5fa27..1949bf376 100644 --- a/taglib/ape/apefile.h +++ b/taglib/ape/apefile.h @@ -48,7 +48,7 @@ namespace TagLib { //! An implementation of APE metadata /*! - * This is implementation of APE metadata. + * this is an implementation of APE metadata. * * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream * properties from the file. @@ -84,7 +84,7 @@ namespace TagLib { }; /*! - * Constructs an APE file from \a file. If \a readProperties is true the + * Constructs an APE file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -93,7 +93,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs an APE file from \a stream. If \a readProperties is true the + * Constructs an APE file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -155,15 +155,15 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid ID3v1 tag. If \a create is \c true it will create * an ID3v1 tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file * on disk actually has an ID3v1 tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the APE::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * @@ -174,15 +174,15 @@ namespace TagLib { /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid APE tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid APE tag. If \a create is \c true it will create * an APE tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an APE tag. Use hasAPETag() to check if the file * on disk actually has an APE tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the APE::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * diff --git a/taglib/ape/apefooter.h b/taglib/ape/apefooter.h index 89b10d2c6..a516d855e 100644 --- a/taglib/ape/apefooter.h +++ b/taglib/ape/apefooter.h @@ -70,17 +70,17 @@ namespace TagLib { unsigned int version() const; /*! - * Returns true if a header is present in the tag. + * Returns \c true if a header is present in the tag. */ bool headerPresent() const; /*! - * Returns true if a footer is present in the tag. + * Returns \c true if a footer is present in the tag. */ bool footerPresent() const; /*! - * Returns true this is actually the header. + * Returns \c true this is actually the header. */ bool isHeader() const; @@ -145,8 +145,8 @@ namespace TagLib { ByteVector renderFooter() const; /*! - * Renders the header corresponding to the footer. If headerPresent is - * set to false, it returns an empty ByteVector. + * Renders the header corresponding to the footer. If headerPresent() is + * \c false, it returns an empty ByteVector. */ ByteVector renderHeader() const; diff --git a/taglib/ape/apeitem.h b/taglib/ape/apeitem.h index c672f653e..8e5e06646 100644 --- a/taglib/ape/apeitem.h +++ b/taglib/ape/apeitem.h @@ -63,7 +63,7 @@ namespace TagLib { /*! * Constructs an item with \a key and \a value. - * If \a binary is true a Binary item will be created, otherwise \a value will be interpreted as text + * If \a binary is \c true a Binary item will be created, otherwise \a value will be interpreted as text */ Item(const String &key, const ByteVector &value, bool binary); @@ -83,7 +83,7 @@ namespace TagLib { Item &operator=(const Item &item); /*! - * Exchanges the content of this item by the content of \a item. + * Exchanges the content of this item with the content of \a item. */ void swap(Item &item) noexcept; @@ -172,7 +172,7 @@ namespace TagLib { void setReadOnly(bool readOnly); /*! - * Return true if the item is read-only. + * Return \c true if the item is read-only. */ bool isReadOnly() const; @@ -189,7 +189,7 @@ namespace TagLib { ItemTypes type() const; /*! - * Returns if the item has any real content. + * Returns \c false if the item has any real content. */ bool isEmpty() const; diff --git a/taglib/ape/apetag.h b/taglib/ape/apetag.h index a4d03c4f0..f3a528056 100644 --- a/taglib/ape/apetag.h +++ b/taglib/ape/apetag.h @@ -116,6 +116,7 @@ namespace TagLib { * * The only conversion done by this export function is to rename the APE tags * TRACK to TRACKNUMBER, YEAR to DATE, and ALBUM ARTIST to ALBUMARTIST, respectively, + * (and a few other keys, see \ref p_propertymapping) * in order to be compliant with the names used in other formats. */ PropertyMap properties() const override; @@ -165,7 +166,7 @@ namespace TagLib { /*! * Adds to the text item specified by \a key the data \a value. If \a replace - * is true, then all of the other values on the same key will be removed + * is \c true, then all of the other values on the same key will be removed * first. If a binary item exists for \a key it will be removed first. */ void addValue(const String &key, const String &value, bool replace = true); @@ -184,7 +185,7 @@ namespace TagLib { void setItem(const String &key, const Item &item); /*! - * Returns true if the tag does not contain any data. + * Returns \c true if the tag does not contain any data. */ bool isEmpty() const override; diff --git a/taglib/asf/asfattribute.h b/taglib/asf/asfattribute.h index 5046065ae..7bb7ba613 100644 --- a/taglib/asf/asfattribute.h +++ b/taglib/asf/asfattribute.h @@ -38,6 +38,8 @@ namespace TagLib class File; class Picture; + //! Attribute of ASF (WMA) metadata + class TAGLIB_EXPORT Attribute { public: @@ -114,7 +116,7 @@ namespace TagLib Attribute &operator=(const Attribute &other); /*! - * Exchanges the content of the Attribute by the content of \a other. + * Exchanges the content of the Attribute with the content of \a other. */ void swap(Attribute &other) noexcept; diff --git a/taglib/asf/asffile.h b/taglib/asf/asffile.h index 5da96dc1b..ec3a9c9c9 100644 --- a/taglib/asf/asffile.h +++ b/taglib/asf/asffile.h @@ -35,6 +35,8 @@ namespace TagLib { //! An implementation of ASF (WMA) metadata namespace ASF { + //! An implementation of TagLib::File with ASF specific methods + /*! * This implements and provides an interface for ASF files to the * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing @@ -112,7 +114,7 @@ namespace TagLib { /*! * Save the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; diff --git a/taglib/asf/asfpicture.h b/taglib/asf/asfpicture.h index 1102458a2..3703d14db 100644 --- a/taglib/asf/asfpicture.h +++ b/taglib/asf/asfpicture.h @@ -50,7 +50,7 @@ namespace TagLib class TAGLIB_EXPORT Picture { public: - /*! + /* * This describes the function or content of the picture. */ DECLARE_PICTURE_TYPE_ENUM(Type) @@ -76,12 +76,12 @@ namespace TagLib Picture& operator=(const Picture& other); /*! - * Exchanges the content of the Picture by the content of \a other. + * Exchanges the content of the Picture with the content of \a other. */ void swap(Picture &other) noexcept; /*! - * Returns true if Picture stores valid picture + * Returns \c true if Picture stores valid picture */ bool isValid() const; @@ -136,7 +136,7 @@ namespace TagLib /*! * Returns the image data as a ByteVector. * - * \note ByteVector has a data() method that returns a const char * which + * \note ByteVector has a data() method that returns a const char * which * should make it easy to export this data to external programs. * * \see setPicture() diff --git a/taglib/asf/asftag.h b/taglib/asf/asftag.h index d1150de34..7ac211ae3 100644 --- a/taglib/asf/asftag.h +++ b/taglib/asf/asftag.h @@ -39,6 +39,8 @@ namespace TagLib { using AttributeList = List; using AttributeListMap = Map; + //! An implementation of ASF (WMA) tags + class TAGLIB_EXPORT Tag : public TagLib::Tag { friend class File; @@ -64,7 +66,7 @@ namespace TagLib { /*! * Returns the album name; if no album name is present in the tag - * String::null will be returned. + * an empty string will be returned. */ String album() const override; @@ -74,7 +76,7 @@ namespace TagLib { String comment() const override; /*! - * Returns the genre name; if no genre is present in the tag String::null + * Returns the genre name; if no genre is present in the tag an empty string * will be returned. */ String genre() const override; @@ -85,7 +87,7 @@ namespace TagLib { virtual String rating() const; /*! - * Returns the genre name; if no genre is present in the tag String::null + * Returns the genre name; if no genre is present in the tag an empty string * will be returned. */ virtual String copyright() const; @@ -112,7 +114,7 @@ namespace TagLib { void setArtist(const String &value) override; /*! - * Sets the album to \a value. If \a value is String::null then this value will be + * Sets the album to \a value. If \a value is an empty string then this value will be * cleared. */ void setAlbum(const String &value) override; @@ -148,7 +150,7 @@ namespace TagLib { void setTrack(unsigned int value) override; /*! - * Returns true if the tag does not contain any data. This should be + * Returns \c true if the tag does not contain any data. This should be * reimplemented in subclasses that provide more than the basic tagging * abilities in this class. */ @@ -168,7 +170,7 @@ namespace TagLib { const AttributeListMap &attributeListMap() const; /*! - * \return True if a value for \a key is currently set. + * \return \c true if a value for \a key is currently set. */ bool contains(const String &key) const; diff --git a/taglib/dsdiff/dsdifffile.h b/taglib/dsdiff/dsdifffile.h index 4871423dc..bbfb2e008 100644 --- a/taglib/dsdiff/dsdifffile.h +++ b/taglib/dsdiff/dsdifffile.h @@ -36,20 +36,21 @@ namespace TagLib { //! An implementation of DSDIFF metadata /*! - * This is implementation of DSDIFF metadata. + * This is an implementation of DSDIFF metadata. * * This supports an ID3v2 tag as well as reading stream from the ID3 RIFF * chunk as well as properties from the file. - * Description of the DSDIFF format is available - * at http://dsd-guide.com/sites/default/files/white-papers/DSDIFF_1.5_Spec.pdf - * DSDIFF standard does not explicitly specify the ID3V2 chunk - * It can be found at the root level, but also sometimes inside the PROP chunk - * In addition, title and artist info are stored as part of the standard + * Description of the DSDIFF format is available at + * + * DSDIFF_1.5_Spec.pdf. + * The DSDIFF standard does not explicitly specify the ID3 chunk. + * It can be found at the root level, but also sometimes inside the PROP chunk. + * In addition, title and artist info are stored as part of the standard. */ namespace DSDIFF { - //! An implementation of TagLib::File with DSDIFF specific methods + //! An implementation of TagLib::File with DSDIFF specific methods. /*! * This implements and provides an interface for DSDIFF files to the @@ -78,7 +79,7 @@ namespace TagLib { }; /*! - * Constructs a DSDIFF file from \a file. If \a readProperties is true + * Constructs a DSDIFF file from \a file. If \a readProperties is \c true * the file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -91,7 +92,7 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs an DSDIFF file from \a stream. If \a readProperties is true + * Constructs an DSDIFF file from \a stream. If \a readProperties is \c true * the file's audio properties will also be read. * * If this file contains an ID3v2 tag, the frames will be created using @@ -168,7 +169,7 @@ namespace TagLib { /*! * Save the file. If at least one tag -- ID3v1 or DIIN -- exists this - * will duplicate its content into the other tag. This returns true + * will duplicate its content into the other tag. This returns \c true * if saving was successful. * * If neither exists or if both tags are empty, this will strip the tags @@ -177,7 +178,7 @@ namespace TagLib { * This is the same as calling save(AllTags); * * If you would like more granular control over the content of the tags, - * with the concession of generality, use paramaterized save call below. + * with the concession of generality, use parameterized save call below. * * \see save(int tags) */ @@ -193,7 +194,7 @@ namespace TagLib { /*! * This will strip the tags that match the OR-ed together TagTypes from the - * file. By default it strips all tags. It returns true if the tags are + * file. By default it strips all tags. It returns \c true if the tags are * successfully stripped. * * \note This will update the file immediately. diff --git a/taglib/dsf/dsffile.cpp b/taglib/dsf/dsffile.cpp index 384f4a3b3..de9572b47 100644 --- a/taglib/dsf/dsffile.cpp +++ b/taglib/dsf/dsffile.cpp @@ -31,8 +31,6 @@ using namespace TagLib; -// The DSF specification is located at http://dsd-guide.com/sites/default/files/white-papers/DSFFileFormatSpec_E.pdf - class DSF::File::FilePrivate { public: diff --git a/taglib/dsf/dsffile.h b/taglib/dsf/dsffile.h index 2372bd421..289376959 100644 --- a/taglib/dsf/dsffile.h +++ b/taglib/dsf/dsffile.h @@ -36,7 +36,27 @@ #include "id3v2tag.h" namespace TagLib { + + //! An implementation of DSF metadata + + /*! + * this is an implementation of DSF metadata using an ID3v2 tag inside the + * metadata chunk. + * The DSF specification is located at + * http://dsd-guide.com/sites/default/files/white-papers/DSFFileFormatSpec_E.pdf + */ + namespace DSF { + + //! An implementation of TagLib::File with DSF specific methods + + /*! + * This implements and provides an interface for DSF files to the + * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing + * the abstract TagLib::File API as well as providing some additional + * information specific to DSF files. + */ + class TAGLIB_EXPORT File : public TagLib::File { public: /*! @@ -103,7 +123,7 @@ namespace TagLib { /*! * Save the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; diff --git a/taglib/dsf/dsfproperties.h b/taglib/dsf/dsfproperties.h index f3ba730e4..ce2491b47 100644 --- a/taglib/dsf/dsfproperties.h +++ b/taglib/dsf/dsfproperties.h @@ -34,6 +34,7 @@ namespace TagLib { namespace DSF { + //! An implementation of audio properties for DSF class TAGLIB_EXPORT Properties : public AudioProperties { public: Properties(const ByteVector &data, ReadStyle style); diff --git a/taglib/fileref.h b/taglib/fileref.h index 749df48a6..e53eafe69 100644 --- a/taglib/fileref.h +++ b/taglib/fileref.h @@ -60,34 +60,12 @@ namespace TagLib { { public: - //! A class for pluggable file type resolution. + //! A class for pluggable file type resolution. - /*! - * This class is used to extend TagLib's very basic file name based file - * type resolution. - * - * This can be accomplished with: - * - * \code - * - * class MyFileTypeResolver : FileTypeResolver - * { - * TagLib::File *createFile(TagLib::FileName *fileName, bool, AudioProperties::ReadStyle) const - * { - * if(someCheckForAnMP3File(fileName)) - * return new TagLib::MPEG::File(fileName); - * return 0; - * } - * } - * - * FileRef::addFileTypeResolver(new MyFileTypeResolver); - * - * \endcode - * - * Naturally a less contrived example would be slightly more complex. This - * can be used to plug in mime-type detection systems or to add new file types - * to TagLib. - */ + /*! + * %File type resolver, better implement StreamTypeResolver in order to + * support both file and stream resolution. + */ class TAGLIB_EXPORT FileTypeResolver { @@ -120,6 +98,44 @@ namespace TagLib { std::unique_ptr d; }; + //! A class for pluggable stream type resolution. + + /*! + * This class is used to extend TagLib's very basic file name based file + * type resolution. + * + * This can be accomplished with: + * + * \code + * + * class MyStreamTypeResolver : StreamTypeResolver + * { + * TagLib::File *createFile(TagLib::FileName *fileName, bool readProps, + * AudioProperties::ReadStyle readStyle) const override + * { + * if(someCheckForAnMP3File(fileName)) + * return new TagLib::MPEG::File(fileName, readProps, readStyle); + * return nullptr; + * } + * + * TagLib::File *createFileFromStream(TagLib::IOStream *s, bool readProps, + * AudioProperties::ReadStyle readStyle) const override + * { + * if(someCheckForAnMP3Stream(s)) + * return new TagLib::MPEG::File(s, readProps, readStyle); + * return nullptr; + * } + * } + * + * FileRef::addFileTypeResolver(new MyStreamTypeResolver); + * + * \endcode + * + * Naturally a less contrived example would be slightly more complex. This + * can be used to plug in mime-type detection systems or to add new file types + * to TagLib. + */ + class TAGLIB_EXPORT StreamTypeResolver : public FileTypeResolver { public: @@ -132,6 +148,17 @@ namespace TagLib { StreamTypeResolver(const StreamTypeResolver &) = delete; StreamTypeResolver &operator=(const StreamTypeResolver &) = delete; + /*! + * This method must be overridden to provide an additional stream type + * resolver. If the resolver is able to determine the file type it should + * return a valid File object; if not it should return nullptr. + * + * \note The created file is then owned by the FileRef and should not be + * deleted. Deletion will happen automatically when the FileRef passes + * out of scope. + * + * \see createFile() + */ virtual File *createFileFromStream(IOStream *stream, bool readAudioProperties = true, AudioProperties::ReadStyle @@ -148,9 +175,9 @@ namespace TagLib { FileRef(); /*! - * Create a FileRef from \a fileName. If \a readAudioProperties is true then + * Create a FileRef from \a fileName. If \a readAudioProperties is \c true then * the audio properties will be read using \a audioPropertiesStyle. If - * \a readAudioProperties is false then \a audioPropertiesStyle will be + * \a readAudioProperties is \c false then \a audioPropertiesStyle will be * ignored. * * Also see the note in the class documentation about why you may not want to @@ -163,8 +190,8 @@ namespace TagLib { /*! * Construct a FileRef from an opened \a IOStream. If \a readAudioProperties - * is true then the audio properties will be read using \a audioPropertiesStyle. - * If \a readAudioProperties is false then \a audioPropertiesStyle will be + * is \c true then the audio properties will be read using \a audioPropertiesStyle. + * If \a readAudioProperties is \c false then \a audioPropertiesStyle will be * ignored. * * Also see the note in the class documentation about why you may not want to @@ -287,7 +314,7 @@ namespace TagLib { /*! * Returns the audio properties for this FileRef. If no audio properties - * were read then this will returns a null pointer. + * were read then this will return a null pointer. */ AudioProperties *audioProperties() const; @@ -309,7 +336,7 @@ namespace TagLib { File *file() const; /*! - * Saves the file. Returns true on success. + * Saves the file. Returns \c true on success. */ bool save(); @@ -351,7 +378,7 @@ namespace TagLib { static StringList defaultFileExtensions(); /*! - * Returns true if the file (and as such other pointers) are null. + * Returns \c true if the file (and as such other pointers) are null. */ bool isNull() const; @@ -361,17 +388,17 @@ namespace TagLib { FileRef &operator=(const FileRef &ref); /*! - * Exchanges the content of the FileRef by the content of \a ref. + * Exchanges the content of the FileRef with the content of \a ref. */ void swap(FileRef &ref) noexcept; /*! - * Returns true if this FileRef and \a ref point to the same File object. + * Returns \c true if this FileRef and \a ref point to the same File object. */ bool operator==(const FileRef &ref) const; /*! - * Returns true if this FileRef and \a ref do not point to the same File + * Returns \c true if this FileRef and \a ref do not point to the same File * object. */ bool operator!=(const FileRef &ref) const; diff --git a/taglib/flac/flacfile.h b/taglib/flac/flacfile.h index 0ee161b73..6ab4762ee 100644 --- a/taglib/flac/flacfile.h +++ b/taglib/flac/flacfile.h @@ -43,7 +43,7 @@ namespace TagLib { //! An implementation of FLAC metadata /*! - * This is implementation of FLAC metadata for non-Ogg FLAC files. At some + * this is an implementation of FLAC metadata for non-Ogg FLAC files. At some * point when Ogg / FLAC is more common there will be a similar implementation * under the Ogg hierarchy. * @@ -83,7 +83,7 @@ namespace TagLib { }; /*! - * Constructs a FLAC file from \a file. If \a readProperties is true the + * Constructs a FLAC file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -96,13 +96,15 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs an FLAC file from \a file. If \a readProperties is true the + * Constructs an FLAC file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * If this file contains an ID3v2 tag, the frames will be created using * \a frameFactory. * * \note In the current implementation, \a propertiesStyle is ignored. + * + * \deprecated Use the constructor above. */ TAGLIB_DEPRECATED File(FileName file, ID3v2::FrameFactory *frameFactory, @@ -110,7 +112,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs a FLAC file from \a stream. If \a readProperties is true the + * Constructs a FLAC file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -126,7 +128,7 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs a FLAC file from \a stream. If \a readProperties is true the + * Constructs a FLAC file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -136,6 +138,8 @@ namespace TagLib { * \a frameFactory. * * \note In the current implementation, \a propertiesStyle is ignored. + * + * \deprecated Use the constructor above. */ TAGLIB_DEPRECATED File(IOStream *stream, ID3v2::FrameFactory *frameFactory, @@ -207,22 +211,22 @@ namespace TagLib { * will also keep any old ID3-tags up to date. If the file * has no XiphComment, one will be constructed from the ID3-tags. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; /*! * Returns a pointer to the ID3v2 tag of the file. * - * If \a create is false (the default) this returns a null pointer - * if there is no valid ID3v2 tag. If \a create is true it will create + * If \a create is \c false (the default) this returns a null pointer + * if there is no valid ID3v2 tag. If \a create is \c true it will create * an ID3v2 tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file * on disk actually has an ID3v2 tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the FLAC::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * @@ -233,15 +237,15 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this returns a null pointer - * if there is no valid APE tag. If \a create is true it will create + * If \a create is \c false (the default) this returns a null pointer + * if there is no valid APE tag. If \a create is \c true it will create * an APE tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file * on disk actually has an ID3v1 tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the FLAC::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * @@ -252,8 +256,8 @@ namespace TagLib { /*! * Returns a pointer to the XiphComment for the file. * - * If \a create is false (the default) this returns a null pointer - * if there is no valid XiphComment. If \a create is true it will create + * If \a create is \c false (the default) this returns a null pointer + * if there is no valid XiphComment. If \a create is \c true it will create * a XiphComment if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the @@ -274,8 +278,8 @@ namespace TagLib { List pictureList(); /*! - * Removes an attached picture. If \a del is true the picture's memory - * will be freed; if it is false, it must be deleted by the user. + * Removes an attached picture. If \a del is \c true the picture's memory + * will be freed; if it is \c false, it must be deleted by the user. */ void removePicture(Picture *picture, bool del = true); diff --git a/taglib/flac/flacmetadatablock.h b/taglib/flac/flacmetadatablock.h index e69a6b041..150c5b54f 100644 --- a/taglib/flac/flacmetadatablock.h +++ b/taglib/flac/flacmetadatablock.h @@ -32,6 +32,7 @@ namespace TagLib { namespace FLAC { + //! FLAC metadata block class TAGLIB_EXPORT MetadataBlock { public: diff --git a/taglib/flac/flacpicture.h b/taglib/flac/flacpicture.h index eb2a630e7..c83867ee3 100644 --- a/taglib/flac/flacpicture.h +++ b/taglib/flac/flacpicture.h @@ -35,11 +35,12 @@ namespace TagLib { namespace FLAC { + //! FLAC picture class TAGLIB_EXPORT Picture : public MetadataBlock { public: - /*! + /* * This describes the function or content of the picture. */ DECLARE_PICTURE_TYPE_ENUM(Type) diff --git a/taglib/flac/flacunknownmetadatablock.h b/taglib/flac/flacunknownmetadatablock.h index d50354d47..e1adfb752 100644 --- a/taglib/flac/flacunknownmetadatablock.h +++ b/taglib/flac/flacunknownmetadatablock.h @@ -33,6 +33,7 @@ namespace TagLib { namespace FLAC { + //! Unknown FLAC metadata block class TAGLIB_EXPORT UnknownMetadataBlock : public MetadataBlock { public: diff --git a/taglib/it/itfile.h b/taglib/it/itfile.h index c7f340d27..8ed8e95bf 100644 --- a/taglib/it/itfile.h +++ b/taglib/it/itfile.h @@ -31,8 +31,23 @@ namespace TagLib { + //! An implementation of Impulse Tracker metadata + + /*! + * this is an implementation of Impulse Tracker metadata. + */ + namespace IT { + //! An implementation of TagLib::File with IT specific methods + + /*! + * This implements and provides an interface for IT files to the + * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing + * the abstract TagLib::File API as well as providing some additional + * information specific to IT files. + */ + class TAGLIB_EXPORT File : public Mod::FileBase { public: /*! diff --git a/taglib/it/itproperties.h b/taglib/it/itproperties.h index 1d118b43d..0aa149a37 100644 --- a/taglib/it/itproperties.h +++ b/taglib/it/itproperties.h @@ -31,6 +31,7 @@ namespace TagLib { namespace IT { + //! An implementation of audio property reading for IT class TAGLIB_EXPORT Properties : public AudioProperties { public: /*! Flag bits. */ diff --git a/taglib/mod/modfile.h b/taglib/mod/modfile.h index f7cd13c98..8f654c996 100644 --- a/taglib/mod/modfile.h +++ b/taglib/mod/modfile.h @@ -34,7 +34,24 @@ #include "modproperties.h" namespace TagLib { + + //! An implementation of Protracker metadata + + /*! + * this is an implementation of Protracker metadata. + */ + namespace Mod { + + //! An implementation of TagLib::File with Mod specific methods + + /*! + * This implements and provides an interface for Mod files to the + * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing + * the abstract TagLib::File API as well as providing some additional + * information specific to Mod files. + */ + class TAGLIB_EXPORT File : public TagLib::Mod::FileBase { public: diff --git a/taglib/mod/modfilebase.h b/taglib/mod/modfilebase.h index 75fceab16..c3839f18d 100644 --- a/taglib/mod/modfilebase.h +++ b/taglib/mod/modfilebase.h @@ -36,6 +36,7 @@ namespace TagLib { namespace Mod { + //! Base class for module files class TAGLIB_EXPORT FileBase : public TagLib::File { public: diff --git a/taglib/mod/modproperties.h b/taglib/mod/modproperties.h index 0cd5384e9..325b1e5a9 100644 --- a/taglib/mod/modproperties.h +++ b/taglib/mod/modproperties.h @@ -31,6 +31,7 @@ namespace TagLib { namespace Mod { + //! An implementation of audio property reading for Mod class TAGLIB_EXPORT Properties : public AudioProperties { public: diff --git a/taglib/mod/modtag.h b/taglib/mod/modtag.h index 974b1cafb..53f40faae 100644 --- a/taglib/mod/modtag.h +++ b/taglib/mod/modtag.h @@ -30,6 +30,9 @@ namespace TagLib { namespace Mod { + + //! A module file tag implementation + /*! * Tags for module files (Mod, S3M, IT, XM). * @@ -53,29 +56,29 @@ namespace TagLib { /*! * Returns the track name; if no track name is present in the tag - * String::null will be returned. + * an empty string will be returned. */ String title() const override; /*! - * Not supported by module files. Therefore always returns String::null. + * Not supported by module files. Therefore always returns an empty string. */ String artist() const override; /*! - * Not supported by module files. Therefore always returns String::null. + * Not supported by module files. Therefore always returns an empty string. */ String album() const override; /*! * Returns the track comment derived from the instrument/sample/pattern - * names; if no comment is present in the tag String::null will be + * names; if no comment is present in the tag an empty string will be * returned. */ String comment() const override; /*! - * Not supported by module files. Therefore always returns String::null. + * Not supported by module files. Therefore always returns an empty string. */ String genre() const override; @@ -94,12 +97,12 @@ namespace TagLib { * Only XM files store this tag to the file as such, for other formats * (Mod, S3M, IT) this is derived from the file type or the flavour of * the file type. Therefore only XM files might have an empty - * (String::null) tracker name. + * tracker name. */ String trackerName() const; /*! - * Sets the title to \a title. If \a title is String::null then this + * Sets the title to \a title. If \a title is an empty string then this * value will be cleared. * * The length limits per file type are (1 character = 1 byte): @@ -119,7 +122,7 @@ namespace TagLib { void setAlbum(const String &album) override; /*! - * Sets the comment to \a comment. If \a comment is String::null then + * Sets the comment to \a comment. If \a comment is an empty string then * this value will be cleared. * * Note that module file formats don't actually support a comment tag. @@ -154,7 +157,7 @@ namespace TagLib { /*! * Sets the tracker name to \a trackerName. If \a trackerName is - * String::null then this value will be cleared. + * an empty string then this value will be cleared. * * Note that only XM files support this tag. Setting the * tracker name for other module file formats will be ignored. diff --git a/taglib/mp4/mp4atom.h b/taglib/mp4/mp4atom.h index cad6cab6d..4fbf9e2da 100644 --- a/taglib/mp4/mp4atom.h +++ b/taglib/mp4/mp4atom.h @@ -33,12 +33,8 @@ #include "tfile.h" #include "tlist.h" -#ifndef DO_NOT_DOCUMENT - namespace TagLib { namespace MP4 { - class Atom; - using AtomList = TagLib::List; enum AtomDataType { TypeImplicit = 0, // for use with tags for which no type needs to be indicated because only one type is allowed @@ -64,6 +60,7 @@ namespace TagLib { TypeUndefined = 255 // undefined }; +#ifndef DO_NOT_DOCUMENT struct AtomData { AtomData(AtomDataType type, const ByteVector &data) : type(type), data(data) { } @@ -72,6 +69,8 @@ namespace TagLib { ByteVector data; }; + class Atom; + using AtomList = TagLib::List; using AtomDataList = TagLib::List; class TAGLIB_EXPORT Atom @@ -116,9 +115,8 @@ namespace TagLib { TAGLIB_MSVC_SUPPRESS_WARNING_NEEDS_TO_HAVE_DLL_INTERFACE std::unique_ptr d; }; +#endif // DO_NOT_DOCUMENT } // namespace MP4 } // namespace TagLib #endif - -#endif diff --git a/taglib/mp4/mp4coverart.h b/taglib/mp4/mp4coverart.h index 253b1bdb1..ec17e687f 100644 --- a/taglib/mp4/mp4coverart.h +++ b/taglib/mp4/mp4coverart.h @@ -33,6 +33,7 @@ namespace TagLib { namespace MP4 { + //! MP4 picture class TAGLIB_EXPORT CoverArt { public: @@ -58,7 +59,7 @@ namespace TagLib { CoverArt &operator=(const CoverArt &item); /*! - * Exchanges the content of the CoverArt by the content of \a item. + * Exchanges the content of the CoverArt with the content of \a item. */ void swap(CoverArt &item) noexcept; diff --git a/taglib/mp4/mp4file.h b/taglib/mp4/mp4file.h index c29c9d898..faf215e45 100644 --- a/taglib/mp4/mp4file.h +++ b/taglib/mp4/mp4file.h @@ -38,6 +38,7 @@ namespace TagLib { class Atoms; class ItemFactory; + //! An implementation of TagLib::File with MP4 specific methods /*! * This implements and provides an interface for MP4 files to the @@ -62,7 +63,7 @@ namespace TagLib { }; /*! - * Constructs an MP4 file from \a file. If \a readProperties is true the + * Constructs an MP4 file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -74,7 +75,7 @@ namespace TagLib { ItemFactory *itemFactory = nullptr); /*! - * Constructs an MP4 file from \a stream. If \a readProperties is true the + * Constructs an MP4 file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -132,13 +133,13 @@ namespace TagLib { /*! * Save the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; /*! * This will strip the tags that match the OR-ed together TagTypes from the - * file. By default it strips all tags. It returns true if the tags are + * file. By default it strips all tags. It returns \c true if the tags are * successfully stripped. * * \note This will update the file immediately. diff --git a/taglib/mp4/mp4item.h b/taglib/mp4/mp4item.h index 962691c9e..f584f0092 100644 --- a/taglib/mp4/mp4item.h +++ b/taglib/mp4/mp4item.h @@ -32,6 +32,7 @@ namespace TagLib { namespace MP4 { + //! MP4 item class TAGLIB_EXPORT Item { public: @@ -48,7 +49,7 @@ namespace TagLib { Item &operator=(const Item &item); /*! - * Exchanges the content of the Item by the content of \a item. + * Exchanges the content of the Item with the content of \a item. */ void swap(Item &item) noexcept; diff --git a/taglib/mp4/mp4tag.h b/taglib/mp4/mp4tag.h index c1da33624..297e24dde 100644 --- a/taglib/mp4/mp4tag.h +++ b/taglib/mp4/mp4tag.h @@ -40,6 +40,7 @@ namespace TagLib { class ItemFactory; + //! An MP4 tag implementation class TAGLIB_EXPORT Tag: public TagLib::Tag { public: @@ -91,7 +92,7 @@ namespace TagLib { void removeItem(const String &key); /*! - * \return True if the tag contains an entry for \a key. + * \return \c true if the tag contains an entry for \a key. */ bool contains(const String &key) const; diff --git a/taglib/mpc/mpcfile.h b/taglib/mpc/mpcfile.h index 66c22961e..76de2bb57 100644 --- a/taglib/mpc/mpcfile.h +++ b/taglib/mpc/mpcfile.h @@ -42,7 +42,7 @@ namespace TagLib { //! An implementation of MPC metadata /*! - * This is implementation of MPC metadata. + * this is an implementation of MPC metadata. * * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream * properties from the file. ID3v2 tags are invalid in MPC-files, but will be skipped @@ -82,7 +82,7 @@ namespace TagLib { }; /*! - * Constructs an MPC file from \a file. If \a readProperties is true the + * Constructs an MPC file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -91,7 +91,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs an MPC file from \a stream. If \a readProperties is true the + * Constructs an MPC file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -141,22 +141,22 @@ namespace TagLib { /*! * Saves the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this returns a null pointer - * if there is no valid APE tag. If \a create is true it will create + * If \a create is \c false (the default) this returns a null pointer + * if there is no valid APE tag. If \a create is \c true it will create * an APE tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file * on disk actually has an ID3v1 tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the MPC::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * @@ -167,8 +167,8 @@ namespace TagLib { /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid APE tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid APE tag. If \a create is \c true it will create * an APE tag if one does not exist and returns a valid pointer. If * there already be an ID3v1 tag, the new APE tag will be placed before it. * @@ -176,7 +176,7 @@ namespace TagLib { * file on disk has an APE tag. Use hasAPETag() to check if the file * on disk actually has an APE tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the MPC::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * diff --git a/taglib/mpc/mpcproperties.h b/taglib/mpc/mpcproperties.h index 2e0984393..dd7e15d43 100644 --- a/taglib/mpc/mpcproperties.h +++ b/taglib/mpc/mpcproperties.h @@ -50,7 +50,7 @@ namespace TagLib { public: /*! * Create an instance of MPC::Properties with the data read directly - * from a MPC::File. + * from an MPC::File. */ Properties(File *file, offset_t streamLength, ReadStyle style = Average); diff --git a/taglib/mpeg/id3v1/id3v1tag.h b/taglib/mpeg/id3v1/id3v1tag.h index 8a780f144..469061f15 100644 --- a/taglib/mpeg/id3v1/id3v1tag.h +++ b/taglib/mpeg/id3v1/id3v1tag.h @@ -38,7 +38,7 @@ namespace TagLib { namespace ID3v1 { - //! A abstraction for the string to data encoding in ID3v1 tags. + //! An abstraction for the string to data encoding in ID3v1 tags. /*! * ID3v1 should in theory always contain ISO-8859-1 (Latin1) data. In diff --git a/taglib/mpeg/id3v2/frames/attachedpictureframe.h b/taglib/mpeg/id3v2/frames/attachedpictureframe.h index 490dbb072..3e65beed7 100644 --- a/taglib/mpeg/id3v2/frames/attachedpictureframe.h +++ b/taglib/mpeg/id3v2/frames/attachedpictureframe.h @@ -50,7 +50,7 @@ namespace TagLib { public: - /*! + /* * This describes the function or content of the picture. */ DECLARE_PICTURE_TYPE_ENUM(Type) @@ -67,7 +67,7 @@ namespace TagLib { explicit AttachedPictureFrame(const ByteVector &data); /*! - * Destroys the AttahcedPictureFrame instance. + * Destroys the AttachedPictureFrame instance. */ ~AttachedPictureFrame() override; @@ -150,7 +150,7 @@ namespace TagLib { /*! * Returns the image data as a ByteVector. * - * \note ByteVector has a data() method that returns a const char * which + * \note ByteVector has a data() method that returns a const char * which * should make it easy to export this data to external programs. * * \see setPicture() diff --git a/taglib/mpeg/id3v2/frames/chapterframe.h b/taglib/mpeg/id3v2/frames/chapterframe.h index ea4a67671..62cb13a5a 100644 --- a/taglib/mpeg/id3v2/frames/chapterframe.h +++ b/taglib/mpeg/id3v2/frames/chapterframe.h @@ -57,7 +57,7 @@ namespace TagLib { * \a startTime, end time \a endTime, start offset \a startOffset, * end offset \a endOffset and optionally a list of embedded frames, * whose ownership will then be taken over by this Frame, in - * \a embeddedFrames; + * \a embeddedFrames. * * All times are in milliseconds. */ @@ -153,7 +153,7 @@ namespace TagLib { void setEndOffset(const unsigned int &eO); /*! - * Returns a reference to the frame list map. This is an FrameListMap of + * Returns a reference to the frame list map. This is a FrameListMap of * all of the frames embedded in the CHAP frame. * * This is the most convenient structure for accessing the CHAP frame's @@ -169,11 +169,11 @@ namespace TagLib { const FrameListMap &embeddedFrameListMap() const; /*! - * Returns a reference to the embedded frame list. This is an FrameList + * Returns a reference to the embedded frame list. This is a FrameList * of all of the frames embedded in the CHAP frame in the order that they * were parsed. * - * This can be useful if for example you want iterate over the CHAP frame's + * This can be useful if for example you want to iterate over the CHAP frame's * embedded frames in the order that they occur in the CHAP frame. * * \warning You should not modify this data structure directly, instead @@ -204,8 +204,8 @@ namespace TagLib { void addEmbeddedFrame(Frame *frame); /*! - * Remove an embedded frame from the CHAP frame. If \a del is true the frame's - * memory will be freed; if it is false, it must be deleted by the user. + * Remove an embedded frame from the CHAP frame. If \a del is \c true the frame's + * memory will be freed; if it is \c false, it must be deleted by the user. * * \note Using this method will invalidate any pointers on the list * returned by embeddedFrameList() diff --git a/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h b/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h index 8dc8f8641..f70976af8 100644 --- a/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h +++ b/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h @@ -137,7 +137,7 @@ namespace TagLib { EventTimingCodesFrame &operator=(const EventTimingCodesFrame &) = delete; /*! - * Returns a null string. + * Returns an empty string. */ String toString() const override; diff --git a/taglib/mpeg/id3v2/frames/generalencapsulatedobjectframe.h b/taglib/mpeg/id3v2/frames/generalencapsulatedobjectframe.h index 9d0b76c6b..d4562dea1 100644 --- a/taglib/mpeg/id3v2/frames/generalencapsulatedobjectframe.h +++ b/taglib/mpeg/id3v2/frames/generalencapsulatedobjectframe.h @@ -151,7 +151,7 @@ namespace TagLib { /*! * Returns the object data as a ByteVector. * - * \note ByteVector has a data() method that returns a const char * which + * \note ByteVector has a data() method that returns a const char * which * should make it easy to export this data to external programs. * * \see setObject() diff --git a/taglib/mpeg/id3v2/frames/ownershipframe.cpp b/taglib/mpeg/id3v2/frames/ownershipframe.cpp index b2a6a0734..01918b872 100644 --- a/taglib/mpeg/id3v2/frames/ownershipframe.cpp +++ b/taglib/mpeg/id3v2/frames/ownershipframe.cpp @@ -127,7 +127,7 @@ void OwnershipFrame::parseFields(const ByteVector &data) d->textEncoding = static_cast(data[0]); pos += 1; - // Read the price paid this is a null terminate string + // Read the price paid, this is a null terminated string d->pricePaid = readStringField(data, String::Latin1, &pos); // If we don't have at least 8 bytes left then don't parse the rest of the diff --git a/taglib/mpeg/id3v2/frames/ownershipframe.h b/taglib/mpeg/id3v2/frames/ownershipframe.h index dddbfd040..0d04744d7 100644 --- a/taglib/mpeg/id3v2/frames/ownershipframe.h +++ b/taglib/mpeg/id3v2/frames/ownershipframe.h @@ -51,7 +51,7 @@ namespace TagLib { explicit OwnershipFrame(String::Type encoding = String::Latin1); /*! - * Construct a ownership based on the data in \a data. + * Construct an ownership frame based on the data in \a data. */ explicit OwnershipFrame(const ByteVector &data); diff --git a/taglib/mpeg/id3v2/frames/podcastframe.h b/taglib/mpeg/id3v2/frames/podcastframe.h index c63e8fa97..da151433c 100644 --- a/taglib/mpeg/id3v2/frames/podcastframe.h +++ b/taglib/mpeg/id3v2/frames/podcastframe.h @@ -56,7 +56,7 @@ namespace TagLib { PodcastFrame &operator=(const PodcastFrame &) = delete; /*! - * Returns a null string. + * Returns an empty string. */ String toString() const override; diff --git a/taglib/mpeg/id3v2/frames/privateframe.h b/taglib/mpeg/id3v2/frames/privateframe.h index b8002573c..ddc4a31bc 100644 --- a/taglib/mpeg/id3v2/frames/privateframe.h +++ b/taglib/mpeg/id3v2/frames/privateframe.h @@ -34,7 +34,7 @@ namespace TagLib { namespace ID3v2 { - //! An implementation of ID3v2 privateframe + //! An implementation of ID3v2 private frame class TAGLIB_EXPORT PrivateFrame : public Frame { diff --git a/taglib/mpeg/id3v2/frames/tableofcontentsframe.h b/taglib/mpeg/id3v2/frames/tableofcontentsframe.h index 0c12c20dd..1e457f232 100644 --- a/taglib/mpeg/id3v2/frames/tableofcontentsframe.h +++ b/taglib/mpeg/id3v2/frames/tableofcontentsframe.h @@ -78,7 +78,7 @@ namespace TagLib { ByteVector elementID() const; /*! - * Returns true, if the frame is top-level (doesn't have + * Returns \c true, if the frame is top-level (doesn't have * any parent CTOC frame). * * \see setIsTopLevel() @@ -86,7 +86,7 @@ namespace TagLib { bool isTopLevel() const; /*! - * Returns true, if the child elements list entries + * Returns \c true, if the child elements list entries * are ordered. * * \see setIsOrdered() @@ -153,7 +153,7 @@ namespace TagLib { void removeChildElement(const ByteVector &cE); /*! - * Returns a reference to the frame list map. This is an FrameListMap of + * Returns a reference to the frame list map. This is a FrameListMap of * all of the frames embedded in the CTOC frame. * * This is the most convenient structure for accessing the CTOC frame's @@ -169,11 +169,11 @@ namespace TagLib { const FrameListMap &embeddedFrameListMap() const; /*! - * Returns a reference to the embedded frame list. This is an FrameList + * Returns a reference to the embedded frame list. This is a FrameList * of all of the frames embedded in the CTOC frame in the order that they * were parsed. * - * This can be useful if for example you want iterate over the CTOC frame's + * This can be useful if for example you want to iterate over the CTOC frame's * embedded frames in the order that they occur in the CTOC frame. * * \warning You should not modify this data structure directly, instead @@ -204,8 +204,8 @@ namespace TagLib { void addEmbeddedFrame(Frame *frame); /*! - * Remove an embedded frame from the CTOC frame. If \a del is true the frame's - * memory will be freed; if it is false, it must be deleted by the user. + * Remove an embedded frame from the CTOC frame. If \a del is \c true the frame's + * memory will be freed; if it is \c false, it must be deleted by the user. * * \note Using this method will invalidate any pointers on the list * returned by embeddedFrameList() diff --git a/taglib/mpeg/id3v2/frames/textidentificationframe.h b/taglib/mpeg/id3v2/frames/textidentificationframe.h index 0d1754568..1dbcdc098 100644 --- a/taglib/mpeg/id3v2/frames/textidentificationframe.h +++ b/taglib/mpeg/id3v2/frames/textidentificationframe.h @@ -59,7 +59,7 @@ namespace TagLib { *
  • TDTG Tagging time
    • *
  • TENC Encoded by
    • *
  • TEXT Lyricist/Text writer
    • - *
  • TFLT File type
    • + *
  • TFLT %File type
    • *
  • TIPL Involved people list
    • *
  • TIT1 Content group description
    • *
  • TIT2 Title/songname/content description
    • @@ -74,7 +74,7 @@ namespace TagLib { *
  • TOFN Original filename
    • *
  • TOLY Original lyricist(s)/text writer(s)
    • *
  • TOPE Original artist(s)/performer(s)
    • - *
  • TOWN File owner/licensee
    • + *
  • TOWN %File owner/licensee
    • *
  • TPE1 Lead performer(s)/Soloist(s)
    • *
  • TPE2 Band/orchestra/accompaniment
    • *
  • TPE3 Conductor/performer refinement
    • diff --git a/taglib/mpeg/id3v2/frames/unknownframe.h b/taglib/mpeg/id3v2/frames/unknownframe.h index 233d7f6eb..213e6fd8a 100644 --- a/taglib/mpeg/id3v2/frames/unknownframe.h +++ b/taglib/mpeg/id3v2/frames/unknownframe.h @@ -37,7 +37,7 @@ namespace TagLib { /*! * This class represents a frame type not known (or more often simply - * unimplemented) in TagLib. This is here provide a basic API for + * unimplemented) in TagLib. This is here to provide a basic API for * manipulating the binary data of unknown frames and to provide a means * of rendering such \e unknown frames. * diff --git a/taglib/mpeg/id3v2/id3v2.h b/taglib/mpeg/id3v2/id3v2.h index 6dfba5fb4..aa6b4bc4a 100644 --- a/taglib/mpeg/id3v2/id3v2.h +++ b/taglib/mpeg/id3v2/id3v2.h @@ -8,6 +8,16 @@ namespace TagLib { * This is a relatively complete and flexible framework for working with ID3v2 * tags. * + * More information about ID3v2 tags can be found at + * - + * id3v2.2.0.txt + * - + * id3v2.3.0.txt + * - + * id3v2.4.0-structure.txt + * - + * id3v2.4.0-frames.txt + * * \see ID3v2::Tag */ namespace ID3v2 { diff --git a/taglib/mpeg/id3v2/id3v2extendedheader.h b/taglib/mpeg/id3v2/id3v2extendedheader.h index 2113b8a34..3b57925e3 100644 --- a/taglib/mpeg/id3v2/id3v2extendedheader.h +++ b/taglib/mpeg/id3v2/id3v2extendedheader.h @@ -42,7 +42,8 @@ namespace TagLib { * the ID3v2 standard. The API is based on the properties of ID3v2 extended * headers specified there. If any of the terms used in this documentation * are unclear please check the specification in the linked section. - * (Structure, 3.2) + * ( + * id3v2.4.0-structure.txt, 3.2) */ class TAGLIB_EXPORT ExtendedHeader diff --git a/taglib/mpeg/id3v2/id3v2frame.h b/taglib/mpeg/id3v2/id3v2frame.h index ed1c21772..fc2976dea 100644 --- a/taglib/mpeg/id3v2/id3v2frame.h +++ b/taglib/mpeg/id3v2/id3v2frame.h @@ -45,10 +45,12 @@ namespace TagLib { /*! * This class is the main ID3v2 frame implementation. In ID3v2, a tag is * split between a collection of frames (which are in turn split into fields - * (Structure, 4) - * (Frames). This class provides an API for + * ( + * id3v2.4.0-structure.txt, 4) + * ( + * id3v2.4.0-frames.txt). This class provides an API for * gathering information about and modifying ID3v2 frames. Functionality - * specific to a given frame type is handed in one of the many subclasses. + * specific to a given frame type is handled in one of the many subclasses. */ class TAGLIB_EXPORT Frame @@ -67,8 +69,11 @@ namespace TagLib { Frame &operator=(const Frame &) = delete; /*! - * Returns the Frame ID (Structure, 4) - * (Frames, 4) + * Returns the Frame ID + * ( + * id3v2.4.0-structure.txt, 4) + * ( + * id3v2.4.0-frames.txt, 4) */ ByteVector frameID() const; @@ -177,7 +182,7 @@ namespace TagLib { explicit Frame(const ByteVector &data); /*! - * This creates an Frame using the header \a h. + * This creates a Frame using the header \a h. * * The ownership of this header will be assigned to the frame and the * header will be deleted when the frame is destroyed. @@ -185,7 +190,7 @@ namespace TagLib { Frame(Header *h); /*! - * Sets the header to \a h. If \a deleteCurrent is true, this will free + * Sets the header to \a h. If \a deleteCurrent is \c true, this will free * the memory of the current header. * * The ownership of this header will be assigned to the frame and the @@ -229,7 +234,7 @@ namespace TagLib { int *position = nullptr); /*! - * Checks a the list of string values to see if they can be used with the + * Checks the list of string values to see if they can be used with the * specified encoding and returns the recommended encoding. This method * also checks the ID3v2 version and makes sure the encoding can be used * in the version specified by the frame's header. @@ -271,7 +276,9 @@ namespace TagLib { //! ID3v2 frame header implementation /*! - * The ID3v2 Frame Header (Structure, 4) + * The ID3v2 Frame Header + * ( + * id3v2.4.0-structure.txt, 4) * * Every ID3v2::Frame has an associated header that gives some general * properties of the frame and also makes it possible to identify the frame @@ -309,8 +316,11 @@ namespace TagLib { void setData(const ByteVector &data, unsigned int version = 4); /*! - * Returns the Frame ID (Structure, 4) - * (Frames, 4) + * Returns the Frame ID + * ( + * id3v2.4.0-structure.txt, 4) + * ( + * id3v2.4.0-frames.txt, 4) */ ByteVector frameID() const; @@ -353,7 +363,7 @@ namespace TagLib { unsigned int size(); /*! - * Returns true if the flag for tag alter preservation is set. + * Returns \c true if the flag for tag alter preservation is set. * * The semantics are a little backwards from what would seem natural * (setting the preservation flag to throw away the frame), but this @@ -365,7 +375,7 @@ namespace TagLib { /*! * Sets the flag for preservation of this frame if the tag is set. If - * this is set to true the frame will not be written when the tag is + * this is set to \c true the frame will not be written when the tag is * saved. * * The semantics are a little backwards from what would seem natural @@ -377,47 +387,47 @@ namespace TagLib { void setTagAlterPreservation(bool preserve); /*! - * Returns true if the flag for file alter preservation is set. + * Returns \c true if the flag for file alter preservation is set. * * \note This flag is currently ignored internally in TagLib. */ bool fileAlterPreservation() const; /*! - * Returns true if the frame is meant to be read only. + * Returns \c true if the frame is meant to be read only. * * \note This flag is currently ignored internally in TagLib. */ bool readOnly() const; /*! - * Returns true if the flag for the grouping identity is set. + * Returns \c true if the flag for the grouping identity is set. * * \note This flag is currently ignored internally in TagLib. */ bool groupingIdentity() const; /*! - * Returns true if compression is enabled for this frame. + * Returns \c true if compression is enabled for this frame. * * \note This flag is currently ignored internally in TagLib. */ bool compression() const; /*! - * Returns true if encryption is enabled for this frame. + * Returns \c true if encryption is enabled for this frame. * * \note This flag is currently ignored internally in TagLib. */ bool encryption() const; /*! - * Returns true if unsynchronisation is enabled for this frame. + * Returns \c true if unsynchronisation is enabled for this frame. */ bool unsynchronisation() const; /*! - * Returns true if the flag for a data length indicator is set. + * Returns \c true if the flag for a data length indicator is set. */ bool dataLengthIndicator() const; diff --git a/taglib/mpeg/id3v2/id3v2framefactory.h b/taglib/mpeg/id3v2/id3v2framefactory.h index 13c4aed90..8f6c579e3 100644 --- a/taglib/mpeg/id3v2/id3v2framefactory.h +++ b/taglib/mpeg/id3v2/id3v2framefactory.h @@ -50,14 +50,15 @@ namespace TagLib { * factory to be the default factory in ID3v2::Tag constructor you can * implement behavior that will allow for new ID3v2::Frame subclasses (also * provided by you) to be used. - * See \c testFrameFactory() in \e tests/test_mpeg.cpp for an example. + * See + * tests/test_id3v2framefactory.cpp for an example. * * This implements both abstract factory and singleton patterns * of which more information is available on the web and in software design - * textbooks (Notably Design Patterns). + * textbooks (notably Design Patterns). * * \note You do not need to use this factory to create new frames to add to - * an ID3v2::Tag. You can instantiate frame subclasses directly (with new) + * an ID3v2::Tag. You can instantiate frame subclasses directly (with \c new) * and add them to a tag using ID3v2::Tag::addFrame() * * \see ID3v2::Tag::addFrame() @@ -115,7 +116,7 @@ namespace TagLib { void setDefaultTextEncoding(String::Type encoding); /*! - * Returns true if defaultTextEncoding() is used. + * Returns \c true if defaultTextEncoding() is used. * The default text encoding is used when setDefaultTextEncoding() has * been called. In this case, reimplementations of FrameFactory should * use defaultTextEncoding() on the frames (having a text encoding field) @@ -144,8 +145,8 @@ namespace TagLib { * is not compatible with the current standard, this method either updates * the frame or indicates that it should be discarded. * - * This method with return true (with or without changes to the frame) if - * this frame should be kept or false if it should be discarded. + * This method with return \c true (with or without changes to the frame) if + * this frame should be kept or \c false if it should be discarded. * * See the id3v2.4.0-changes.txt document for further information. */ @@ -157,7 +158,7 @@ namespace TagLib { * \param data data of the frame (might be modified) * \param tagHeader the tag header * \return {header, ok}: header is a created frame header or nullptr - * if the frame is invalid; ok is true if the frame is supported. + * if the frame is invalid; ok is \c true if the frame is supported. */ std::pair prepareFrameHeader( ByteVector &data, const Header *tagHeader) const; diff --git a/taglib/mpeg/id3v2/id3v2header.h b/taglib/mpeg/id3v2/id3v2header.h index 1c6313c94..53a22ee71 100644 --- a/taglib/mpeg/id3v2/id3v2header.h +++ b/taglib/mpeg/id3v2/id3v2header.h @@ -42,7 +42,8 @@ namespace TagLib { * the ID3v2 standard. The API is based on the properties of ID3v2 headers * specified there. If any of the terms used in this documentation are * unclear please check the specification in the linked section. - * (Structure, 3.1) + * ( + * id3v2.4.0-structure.txt, 3.1) */ class TAGLIB_EXPORT Header @@ -91,22 +92,22 @@ namespace TagLib { unsigned int revisionNumber() const; /*! - * Returns true if unsynchronisation has been applied to all frames. + * Returns \c true if unsynchronisation has been applied to all frames. */ bool unsynchronisation() const; /*! - * Returns true if an extended header is present in the tag. + * Returns \c true if an extended header is present in the tag. */ bool extendedHeader() const; /*! - * Returns true if the experimental indicator flag is set. + * Returns \c true if the experimental indicator flag is set. */ bool experimentalIndicator() const; /*! - * Returns true if a footer is present in the tag. + * Returns \c true if a footer is present in the tag. */ bool footerPresent() const; /*! diff --git a/taglib/mpeg/id3v2/id3v2synchdata.h b/taglib/mpeg/id3v2/id3v2synchdata.h index 0edce13b0..c91774ffe 100644 --- a/taglib/mpeg/id3v2/id3v2synchdata.h +++ b/taglib/mpeg/id3v2/id3v2synchdata.h @@ -47,8 +47,9 @@ namespace TagLib { { /*! * This returns the unsigned integer value of \a data where \a data is a - * ByteVector that contains a \e synchsafe integer (Structure, - * 6.2). The default \a length of + * ByteVector that contains a \e synchsafe integer + * ( + * id3v2.4.0-structure.txt, 6.2). The default \a length of * 4 is used if another value is not specified. */ TAGLIB_EXPORT unsigned int toUInt(const ByteVector &data); diff --git a/taglib/mpeg/id3v2/id3v2tag.h b/taglib/mpeg/id3v2/id3v2tag.h index 3cf4fb736..929cb3092 100644 --- a/taglib/mpeg/id3v2/id3v2tag.h +++ b/taglib/mpeg/id3v2/id3v2tag.h @@ -88,18 +88,18 @@ namespace TagLib { /*! * This is the main class in the ID3v2 implementation. It serves two - * functions. This first, as is obvious from the public API, is to provide a + * functions. The first, as is obvious from the public API, is to provide a * container for the other ID3v2 related classes. In addition, through the * read() and parse() protected methods, it provides the most basic level of * parsing. In these methods the ID3v2 tag is extracted from the file and * split into data components. * * ID3v2 tags have several parts, TagLib attempts to provide an interface - * for them all. header(), footer() and extendedHeader() correspond to those + * for them all. header() and extendedHeader() correspond to those * data structures in the ID3v2 standard and the APIs for the classes that * they return attempt to reflect this. * - * Also ID3v2 tags are built up from a list of frames, which are in turn + * Also ID3v2 tags are built up from a list of frames, which * have a header and a list of fields. TagLib provides two ways of accessing * the list of frames that are in a given ID3v2 tag. The first is simply * via the frameList() method. This is just a list of pointers to the frames. @@ -126,7 +126,7 @@ namespace TagLib { * with said spec (which is distributed with the TagLib sources). TagLib * tries to do most of the work, but with a little luck, you can still * convince it to generate invalid ID3v2 tags. The APIs for ID3v2 assume a - * working knowledge of ID3v2 structure. You're been warned. + * working knowledge of ID3v2 structure. You've been warned. */ class TAGLIB_EXPORT Tag : public TagLib::Tag @@ -194,7 +194,7 @@ namespace TagLib { ExtendedHeader *extendedHeader() const; /*! - * Returns a reference to the frame list map. This is an FrameListMap of + * Returns a reference to the frame list map. This is a FrameListMap of * all of the frames in the tag. * * This is the most convenient structure for accessing the tag's frames. @@ -230,10 +230,10 @@ namespace TagLib { const FrameListMap &frameListMap() const; /*! - * Returns a reference to the frame list. This is an FrameList of all of + * Returns a reference to the frame list. This is a FrameList of all of * the frames in the tag in the order that they were parsed. * - * This can be useful if for example you want iterate over the tag's frames + * This can be useful if for example you want to iterate over the tag's frames * in the order that they occur in the tag. * * \warning You should not modify this data structure directly, instead @@ -264,8 +264,8 @@ namespace TagLib { void addFrame(Frame *frame); /*! - * Remove a frame from the tag. If \a del is true the frame's memory - * will be freed; if it is false, it must be deleted by the user. + * Remove a frame from the tag. If \a del is \c true the frame's memory + * will be freed; if it is \c false, it must be deleted by the user. * * \note Using this method will invalidate any pointers on the list * returned by frameList() diff --git a/taglib/mpeg/mpegfile.h b/taglib/mpeg/mpegfile.h index 708729434..3c3e62d26 100644 --- a/taglib/mpeg/mpegfile.h +++ b/taglib/mpeg/mpegfile.h @@ -71,7 +71,7 @@ namespace TagLib { }; /*! - * Constructs an MPEG file from \a file. If \a readProperties is true the + * Constructs an MPEG file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * If \a propertiesStyle is not Fast, the file will be scanned @@ -85,7 +85,7 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs an MPEG file from \a file. If \a readProperties is true the + * Constructs an MPEG file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * If this file contains an ID3v2 tag, the frames will be created using @@ -93,6 +93,8 @@ namespace TagLib { * * If \a propertiesStyle is not Fast, the file will be scanned * completely if no ID3v2 tag or MPEG sync code is found at the start. + * + * \deprecated Use the constructor above. */ TAGLIB_DEPRECATED File(FileName file, ID3v2::FrameFactory *frameFactory, @@ -100,7 +102,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs an MPEG file from \a stream. If \a readProperties is true the + * Constructs an MPEG file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -120,7 +122,7 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs an MPEG file from \a stream. If \a readProperties is true the + * Constructs an MPEG file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -131,6 +133,8 @@ namespace TagLib { * * If \a propertiesStyle is not Fast, the file will be scanned * completely if no ID3v2 tag or MPEG sync code is found at the start. + * + * \deprecated Use the constructor above. */ TAGLIB_DEPRECATED File(IOStream *stream, ID3v2::FrameFactory *frameFactory, @@ -192,7 +196,7 @@ namespace TagLib { /*! * Save the file. If at least one tag -- ID3v1 or ID3v2 -- exists this - * will duplicate its content into the other tag. This returns true + * will duplicate its content into the other tag. This returns \c true * if saving was successful. * * If neither exists or if both tags are empty, this will strip the tags @@ -217,7 +221,7 @@ namespace TagLib { * \a version specifies the ID3v2 version to be used for writing tags. By * default, the latest standard, ID3v2.4 is used. * - * If \a duplicate is set to DuplicateTags and at least one tag -- ID3v1 + * If \a duplicate is set to Duplicate and at least one tag -- ID3v1 * or ID3v2 -- exists this will duplicate its content into the other tag. */ bool save(int tags, StripTags strip = StripOthers, @@ -227,8 +231,8 @@ namespace TagLib { /*! * Returns a pointer to the ID3v2 tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid ID3v2 tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid ID3v2 tag. If \a create is \c true it will create * an ID3v2 tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the @@ -246,8 +250,8 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid ID3v1 tag. If \a create is \c true it will create * an ID3v1 tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the @@ -265,8 +269,8 @@ namespace TagLib { /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid APE tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid APE tag. If \a create is \c true it will create * an APE tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the @@ -283,10 +287,10 @@ namespace TagLib { /*! * This will strip the tags that match the OR-ed together TagTypes from the - * file. By default it strips all tags. It returns true if the tags are + * file. By default it strips all tags. It returns \c true if the tags are * successfully stripped. * - * If \a freeMemory is true the ID3 and APE tags will be deleted and + * If \a freeMemory is \c true the ID3 and APE tags will be deleted and * pointers to them will be invalidated. * * \note This will update the file immediately. @@ -300,13 +304,13 @@ namespace TagLib { /*! * Returns the position in the file of the next MPEG frame, - * using the current position as start + * using the current position as start. */ offset_t nextFrameOffset(offset_t position); /*! * Returns the position in the file of the previous MPEG frame, - * using the current position as start + * using the current position as start. */ offset_t previousFrameOffset(offset_t position); diff --git a/taglib/mpeg/mpegheader.h b/taglib/mpeg/mpegheader.h index 41260e9cf..233656988 100644 --- a/taglib/mpeg/mpegheader.h +++ b/taglib/mpeg/mpegheader.h @@ -42,9 +42,12 @@ namespace TagLib { /*! * This is an implementation of MPEG Layer III headers. The API follows more - * or less the binary format of these headers. I've used - * this - * document as a reference. + * or less the binary format of these headers. + * + * See these documents as a reference + * - + * MPEG Audio Layer I/II/III frame header + * - ADTS */ class TAGLIB_EXPORT Header @@ -53,7 +56,7 @@ namespace TagLib { /*! * Parses an MPEG header based on \a file and \a offset. * - * \note If \a checkLength is true, this requires the next MPEG frame to + * \note If \a checkLength is \c true, this requires the next MPEG frame to * check if the frame length is parsed and calculated correctly. So it's * suitable for seeking for the first valid frame. */ @@ -70,7 +73,7 @@ namespace TagLib { virtual ~Header(); /*! - * Returns true if the frame is at least an appropriate size and has + * Returns \c true if the frame is at least an appropriate size and has * legal values. */ bool isValid() const; @@ -100,7 +103,7 @@ namespace TagLib { int layer() const; /*! - * Returns true if the MPEG protection bit is enabled. + * Returns \c true if the MPEG protection bit is enabled. */ bool protectionEnabled() const; @@ -115,7 +118,7 @@ namespace TagLib { int sampleRate() const; /*! - * Returns true if the frame is padded. + * Returns \c true if the frame is padded. */ bool isPadded() const; @@ -143,13 +146,24 @@ namespace TagLib { * MPEG-4 channel configuration. */ enum ChannelConfiguration { + //! Defined in audio object type (AOT) specific configuration Custom = 0, + //! 1 channel: front-center FrontCenter = 1, + //! 2 channels: front-left, front-right FrontLeftRight = 2, + //! 3 channels: front-center, front-left, front-right FrontCenterLeftRight = 3, + //! 4 channels: front-center, front-left, front-right, back-center FrontCenterLeftRightBackCenter = 4, + //! 5 channels: front-center, front-left, front-right, back-left, + //! back-right FrontCenterLeftRightBackLeftRight = 5, + //! 6 channels: front-center, front-left, front-right, back-left, + //! back-right, LFE-channel FrontCenterLeftRightBackLeftRightLFE = 6, + //! 8 channels: front-center, front-left, front-right, side-left, + //! side-right, back-left, back-right, LFE-channel FrontCenterLeftRightSideLeftRightBackLeftRightLFE = 7 }; @@ -159,18 +173,18 @@ namespace TagLib { ChannelConfiguration channelConfiguration() const; /*! - * Returns true if this is the header of an Audio Data Transport Stream + * Returns \c true if this is the header of an Audio Data Transport Stream * (ADTS), usually AAC. */ bool isADTS() const; /*! - * Returns true if the copyrighted bit is set. + * Returns \c true if the copyrighted bit is set. */ bool isCopyrighted() const; /*! - * Returns true if the "original" bit is set. + * Returns \c true if the "original" bit is set. */ bool isOriginal() const; diff --git a/taglib/mpeg/mpegproperties.h b/taglib/mpeg/mpegproperties.h index 3b7c7e6e5..c92a3b030 100644 --- a/taglib/mpeg/mpegproperties.h +++ b/taglib/mpeg/mpegproperties.h @@ -100,7 +100,7 @@ namespace TagLib { int layer() const; /*! - * Returns true if the MPEG protection bit is enabled. + * Returns \c true if the MPEG protection bit is enabled. */ bool protectionEnabled() const; @@ -115,17 +115,17 @@ namespace TagLib { Header::ChannelConfiguration channelConfiguration() const; /*! - * Returns true for an Audio Data Transport Stream (ADTS), usually AAC. + * Returns \c true for an Audio Data Transport Stream (ADTS), usually AAC. */ bool isADTS() const; /*! - * Returns true if the copyrighted bit is set. + * Returns \c true if the copyrighted bit is set. */ bool isCopyrighted() const; /*! - * Returns true if the "original" bit is set. + * Returns \c true if the "original" bit is set. */ bool isOriginal() const; diff --git a/taglib/mpeg/xingheader.h b/taglib/mpeg/xingheader.h index 25e664c5d..88128d00c 100644 --- a/taglib/mpeg/xingheader.h +++ b/taglib/mpeg/xingheader.h @@ -45,8 +45,8 @@ namespace TagLib { * to make it easy to compute the length and quality of a VBR stream. Our * implementation is only concerned with the total size of the stream (so * that we can calculate the total playing time and the average bitrate). - * It uses - * this text and the XMMS sources as references. + * It uses + * mp3extensions.txt and the XMMS sources as references. */ class TAGLIB_EXPORT XingHeader @@ -88,7 +88,7 @@ namespace TagLib { XingHeader &operator=(const XingHeader &) = delete; /*! - * Returns true if the data was parsed properly and if there is a valid + * Returns \c true if the data was parsed properly and if there is a valid * Xing/VBRI header present. */ bool isValid() const; diff --git a/taglib/ogg/flac/oggflacfile.h b/taglib/ogg/flac/oggflacfile.h index 4d4d4d518..0ca268757 100644 --- a/taglib/ogg/flac/oggflacfile.h +++ b/taglib/ogg/flac/oggflacfile.h @@ -40,7 +40,7 @@ namespace TagLib { //! An implementation of Ogg FLAC metadata /*! - * This is implementation of FLAC metadata for Ogg FLAC files. For "pure" + * this is an implementation of FLAC metadata for Ogg FLAC files. For "pure" * FLAC files look under the FLAC hierarchy. * * Unlike "pure" FLAC-files, Ogg FLAC only supports Xiph-comments, @@ -63,7 +63,7 @@ namespace TagLib { { public: /*! - * Constructs an Ogg/FLAC file from \a file. If \a readProperties is true + * Constructs an Ogg/FLAC file from \a file. If \a readProperties is \c true * the file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -72,7 +72,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs an Ogg/FLAC file from \a stream. If \a readProperties is true + * Constructs an Ogg/FLAC file from \a stream. If \a readProperties is \c true * the file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -98,7 +98,7 @@ namespace TagLib { * the file on disk has a XiphComment. Use hasXiphComment() to check if * the file on disk actually has a XiphComment. * - * \note The Tag is still owned by the FLAC::File and should not be + * \note The Tag is still owned by the Ogg::FLAC::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * @@ -128,7 +128,7 @@ namespace TagLib { /*! * Save the file. This will primarily save and update the XiphComment. - * Returns true if the save is successful. + * Returns \c true if the save is successful. */ bool save() override; diff --git a/taglib/ogg/oggpage.h b/taglib/ogg/oggpage.h index 4fc9f5a46..f06968364 100644 --- a/taglib/ogg/oggpage.h +++ b/taglib/ogg/oggpage.h @@ -174,7 +174,7 @@ namespace TagLib { * Pack \a packets into Ogg pages using the \a strategy for pagination. * The page number indicator inside of the rendered packets will start * with \a firstPage and be incremented for each page rendered. - * \a containsLastPacket should be set to true if \a packets contains the + * \a containsLastPacket should be set to \c true if \a packets contains the * last page in the stream and will set the appropriate flag in the last * rendered Ogg page's header. \a streamSerialNumber should be set to * the serial number for this stream. diff --git a/taglib/ogg/oggpageheader.h b/taglib/ogg/oggpageheader.h index b177c55d9..6b61196da 100644 --- a/taglib/ogg/oggpageheader.h +++ b/taglib/ogg/oggpageheader.h @@ -63,7 +63,7 @@ namespace TagLib { PageHeader &operator=(const PageHeader &) = delete; /*! - * Returns true if the header parsed properly and is valid. + * Returns \c true if the header parsed properly and is valid. */ bool isValid() const; @@ -87,7 +87,7 @@ namespace TagLib { /*! * Some packets can be continued across multiple pages. If the * first packet in the current page is a continuation this will return - * true. If this is page starts with a new packet this will return false. + * \c true. If this is page starts with a new packet this will return \c false. * * \see lastPacketCompleted() * \see setFirstPacketContinued() @@ -103,7 +103,7 @@ namespace TagLib { void setFirstPacketContinued(bool continued); /*! - * Returns true if the last packet of this page is completely contained in + * Returns \c true if the last packet of this page is completely contained in * this page. * * \see firstPacketContinued() @@ -120,7 +120,7 @@ namespace TagLib { void setLastPacketCompleted(bool completed); /*! - * This returns true if this is the first page of the Ogg (logical) stream. + * This returns \c true if this is the first page of the Ogg (logical) stream. * * \see setFirstPageOfStream() */ @@ -134,7 +134,7 @@ namespace TagLib { void setFirstPageOfStream(bool first); /*! - * This returns true if this is the last page of the Ogg (logical) stream. + * This returns \c true if this is the last page of the Ogg (logical) stream. * * \see setLastPageOfStream() */ diff --git a/taglib/ogg/opus/opusfile.h b/taglib/ogg/opus/opusfile.h index 0d8a8975d..9918bbca0 100644 --- a/taglib/ogg/opus/opusfile.h +++ b/taglib/ogg/opus/opusfile.h @@ -55,7 +55,7 @@ namespace TagLib { { public: /*! - * Constructs an Opus file from \a file. If \a readProperties is true the + * Constructs an Opus file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -64,7 +64,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs an Opus file from \a stream. If \a readProperties is true the + * Constructs an Opus file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -111,7 +111,7 @@ namespace TagLib { /*! * Save the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; diff --git a/taglib/ogg/speex/speexfile.h b/taglib/ogg/speex/speexfile.h index 771e9ab27..284f2ca4b 100644 --- a/taglib/ogg/speex/speexfile.h +++ b/taglib/ogg/speex/speexfile.h @@ -55,7 +55,7 @@ namespace TagLib { { public: /*! - * Constructs a Speex file from \a file. If \a readProperties is true the + * Constructs a Speex file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -64,7 +64,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs a Speex file from \a stream. If \a readProperties is true the + * Constructs a Speex file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -111,7 +111,7 @@ namespace TagLib { /*! * Save the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; diff --git a/taglib/ogg/vorbis/vorbisfile.h b/taglib/ogg/vorbis/vorbisfile.h index c69a5a215..10f0ec944 100644 --- a/taglib/ogg/vorbis/vorbisfile.h +++ b/taglib/ogg/vorbis/vorbisfile.h @@ -64,7 +64,7 @@ namespace TagLib { { public: /*! - * Constructs a Vorbis file from \a file. If \a readProperties is true the + * Constructs a Vorbis file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -73,7 +73,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs a Vorbis file from \a stream. If \a readProperties is true the + * Constructs a Vorbis file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -121,7 +121,7 @@ namespace TagLib { /*! * Save the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; diff --git a/taglib/ogg/xiphcomment.h b/taglib/ogg/xiphcomment.h index 39ee64472..13becb5dd 100644 --- a/taglib/ogg/xiphcomment.h +++ b/taglib/ogg/xiphcomment.h @@ -184,7 +184,7 @@ namespace TagLib { /*! * Add the field specified by \a key with the data \a value. If \a replace - * is true, then all of the other fields with the same key will be removed + * is \c true, then all of the other fields with the same key will be removed * first. * * If the field value is empty, the field will be removed. @@ -213,7 +213,7 @@ namespace TagLib { void removeAllFields(); /*! - * Returns true if the field is contained within the comment. + * Returns \c true if the field is contained within the comment. * * \note This is safer than checking for membership in the FieldListMap. */ @@ -222,7 +222,7 @@ namespace TagLib { /*! * Renders the comment to a ByteVector suitable for inserting into a file. * - * If \a addFramingBit is true the standard Vorbis comment framing bit will + * If \a addFramingBit is \c true the standard Vorbis comment framing bit will * be appended. However some formats (notably FLAC) do not work with this * in place. */ @@ -235,8 +235,8 @@ namespace TagLib { List pictureList(); /*! - * Removes an picture. If \a del is true the picture's memory - * will be freed; if it is false, it must be deleted by the user. + * Removes an picture. If \a del is \c true the picture's memory + * will be freed; if it is \c false, it must be deleted by the user. */ void removePicture(FLAC::Picture *picture, bool del = true); diff --git a/taglib/riff/aiff/aifffile.h b/taglib/riff/aiff/aifffile.h index 0a0cee35c..4619ae5ca 100644 --- a/taglib/riff/aiff/aifffile.h +++ b/taglib/riff/aiff/aifffile.h @@ -37,7 +37,7 @@ namespace TagLib { //! An implementation of AIFF metadata /*! - * This is implementation of AIFF metadata. + * this is an implementation of AIFF metadata. * * This supports an ID3v2 tag as well as reading stream from the ID3 RIFF * chunk as well as properties from the file. @@ -58,7 +58,7 @@ namespace TagLib { { public: /*! - * Constructs an AIFF file from \a file. If \a readProperties is true the + * Constructs an AIFF file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -71,7 +71,7 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs an AIFF file from \a stream. If \a readProperties is true the + * Constructs an AIFF file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is diff --git a/taglib/riff/aiff/aiffproperties.h b/taglib/riff/aiff/aiffproperties.h index 72cdc5639..2c8f9100a 100644 --- a/taglib/riff/aiff/aiffproperties.h +++ b/taglib/riff/aiff/aiffproperties.h @@ -94,7 +94,7 @@ namespace TagLib { unsigned int sampleFrames() const; /*! - * Returns true if the file is in AIFF-C format, false if AIFF format. + * Returns \c true if the file is in AIFF-C format, \c false if AIFF format. */ bool isAiffC() const; diff --git a/taglib/riff/rifffile.h b/taglib/riff/rifffile.h index 78ed38e4d..3dd4cf566 100644 --- a/taglib/riff/rifffile.h +++ b/taglib/riff/rifffile.h @@ -119,7 +119,7 @@ namespace TagLib { * given name already exists it will be overwritten, otherwise it will be * created after the existing chunks. * - * \note If \a alwaysCreate is true, a new chunk is created regardless of + * \note If \a alwaysCreate is \c true, a new chunk is created regardless of * whether or not the chunk \a name exists. It should only be used for * "LIST" chunks. * diff --git a/taglib/riff/wav/infotag.h b/taglib/riff/wav/infotag.h index db506e420..95b0451e3 100644 --- a/taglib/riff/wav/infotag.h +++ b/taglib/riff/wav/infotag.h @@ -37,13 +37,13 @@ namespace TagLib { class File; - //! A RIFF INFO tag implementation. namespace RIFF { + //! A RIFF INFO tag implementation. namespace Info { using FieldListMap = Map; - //! A abstraction for the string to data encoding in Info tags. + //! An abstraction for the string to data encoding in Info tags. /*! * RIFF INFO tag has no clear definitions about character encodings. @@ -84,7 +84,7 @@ namespace TagLib { std::unique_ptr d; }; - //! The main class in the ID3v2 implementation + //! The main class in the INFO tag implementation /*! * This is the main class in the INFO tag implementation. RIFF INFO tag is a @@ -147,22 +147,22 @@ namespace TagLib { */ FieldListMap fieldListMap() const; - /* + /*! * Gets the value of the field with the ID \a id. */ String fieldText(const ByteVector &id) const; - /* - * Sets the value of the field with the ID \a id to \a s. - * If the field does not exist, it is created. - * If \s is empty, the field is removed. - * - * \note fieldId must be four-byte long pure ASCII string. This function - * performs nothing if fieldId is invalid. - */ + /*! + * Sets the value of the field with the ID \a id to \a s. + * If the field does not exist, it is created. + * If \a s is empty, the field is removed. + * + * \note fieldId must be four-byte long pure ASCII string. This function + * performs nothing if fieldId is invalid. + */ void setFieldText(const ByteVector &id, const String &s); - /* + /*! * Removes the field with the ID \a id. */ void removeField(const ByteVector &id); diff --git a/taglib/riff/wav/wavfile.h b/taglib/riff/wav/wavfile.h index cfb4de80b..b457563af 100644 --- a/taglib/riff/wav/wavfile.h +++ b/taglib/riff/wav/wavfile.h @@ -38,7 +38,7 @@ namespace TagLib { //! An implementation of WAV metadata /*! - * This is implementation of WAV metadata. + * this is an implementation of WAV metadata. * * This supports an ID3v2 tag as well as reading stream from the ID3 RIFF * chunk as well as properties from the file. @@ -70,7 +70,7 @@ namespace TagLib { }; /*! - * Constructs a WAV file from \a file. If \a readProperties is true the + * Constructs a WAV file from \a file. If \a readProperties is \c true the * file's audio properties will also be read. * * \note In the current implementation, \a propertiesStyle is ignored. @@ -83,7 +83,7 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs a WAV file from \a stream. If \a readProperties is true the + * Constructs a WAV file from \a stream. If \a readProperties is \c true the * file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -136,7 +136,7 @@ namespace TagLib { /*! * This will strip the tags that match the OR-ed together TagTypes from the - * file. By default it strips all tags. It returns true if the tags are + * file. By default it strips all tags. It returns \c true if the tags are * successfully stripped. * * \note This will update the file immediately. diff --git a/taglib/s3m/s3mfile.h b/taglib/s3m/s3mfile.h index 690d397f9..f50bc0f9c 100644 --- a/taglib/s3m/s3mfile.h +++ b/taglib/s3m/s3mfile.h @@ -35,8 +35,23 @@ namespace TagLib { + //! An implementation of ScreamTracker III metadata + + /*! + * this is an implementation of ScreamTracker III metadata. + */ + namespace S3M { + //! An implementation of TagLib::File with S3M specific methods + + /*! + * This implements and provides an interface for S3M files to the + * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing + * the abstract TagLib::File API as well as providing some additional + * information specific to S3M files. + */ + class TAGLIB_EXPORT File : public Mod::FileBase { public: /*! diff --git a/taglib/s3m/s3mproperties.h b/taglib/s3m/s3mproperties.h index d6c74d28d..8b3feb1fd 100644 --- a/taglib/s3m/s3mproperties.h +++ b/taglib/s3m/s3mproperties.h @@ -31,6 +31,7 @@ namespace TagLib { namespace S3M { + //! An implementation of audio property reading for S3M class TAGLIB_EXPORT Properties : public AudioProperties { public: /*! Flag bits. */ diff --git a/taglib/tag.h b/taglib/tag.h index 24d73c4ed..ed9a53ed0 100644 --- a/taglib/tag.h +++ b/taglib/tag.h @@ -33,7 +33,9 @@ namespace TagLib { - //! A simple, generic interface to common audio meta data fields + class PropertyMap; + + //! A simple, generic interface to common audio meta data fields. /*! * This is an attempt to abstract away the difference in the meta data formats @@ -43,8 +45,6 @@ namespace TagLib { * in TagLib::AudioProperties, TagLib::File and TagLib::FileRef. */ - class PropertyMap; - class TAGLIB_EXPORT Tag { public: @@ -125,30 +125,30 @@ namespace TagLib { /*! * Returns the track name; if no track name is present in the tag - * String::null will be returned. + * an empty string will be returned. */ virtual String title() const = 0; /*! * Returns the artist name; if no artist name is present in the tag - * String::null will be returned. + * an empty string will be returned. */ virtual String artist() const = 0; /*! * Returns the album name; if no album name is present in the tag - * String::null will be returned. + * an empty string will be returned. */ virtual String album() const = 0; /*! * Returns the track comment; if no comment is present in the tag - * String::null will be returned. + * an empty string will be returned. */ virtual String comment() const = 0; /*! - * Returns the genre name; if no genre is present in the tag String::null + * Returns the genre name; if no genre is present in the tag an empty string * will be returned. */ virtual String genre() const = 0; @@ -165,31 +165,31 @@ namespace TagLib { virtual unsigned int track() const = 0; /*! - * Sets the title to \a s. If \a s is String::null then this value will be + * Sets the title to \a s. If \a s is an empty string then this value will be * cleared. */ virtual void setTitle(const String &s) = 0; /*! - * Sets the artist to \a s. If \a s is String::null then this value will be + * Sets the artist to \a s. If \a s is an empty string then this value will be * cleared. */ virtual void setArtist(const String &s) = 0; /*! - * Sets the album to \a s. If \a s is String::null then this value will be + * Sets the album to \a s. If \a s is an empty string then this value will be * cleared. */ virtual void setAlbum(const String &s) = 0; /*! - * Sets the comment to \a s. If \a s is String::null then this value will be + * Sets the comment to \a s. If \a s is an empty string then this value will be * cleared. */ virtual void setComment(const String &s) = 0; /*! - * Sets the genre to \a s. If \a s is String::null then this value will be + * Sets the genre to \a s. If \a s is an empty string then this value will be * cleared. For tag formats that use a fixed set of genres, the appropriate * value will be selected based on a string comparison. A list of available * genres for those formats should be available in that type's @@ -208,7 +208,7 @@ namespace TagLib { virtual void setTrack(unsigned int i) = 0; /*! - * Returns true if the tag does not contain any data. This should be + * Returns \c true if the tag does not contain any data. This should be * reimplemented in subclasses that provide more than the basic tagging * abilities in this class. */ @@ -222,8 +222,8 @@ namespace TagLib { * set, this will not modify or copy that. This just copies using the API * in this class. * - * If \a overwrite is true then the values will be unconditionally copied. - * If false only empty values will be overwritten. + * If \a overwrite is \c true then the values will be unconditionally copied. + * If \c false only empty values will be overwritten. */ static void duplicate(const Tag *source, Tag *target, bool overwrite = true); diff --git a/taglib/toolkit/taglib.h b/taglib/toolkit/taglib.h index 8d65c1ea0..a53a871a1 100644 --- a/taglib/toolkit/taglib.h +++ b/taglib/toolkit/taglib.h @@ -78,7 +78,7 @@ namespace TagLib { #endif /*! - * Unfortunately std::wstring isn't defined on some systems, (i.e. GCC < 3) + * Unfortunately \c std::wstring isn't defined on some systems, (i.e. GCC < 3) * so I'm providing something here that should be constant. */ using wstring = std::basic_string; @@ -89,7 +89,7 @@ namespace TagLib { * * \section intro Introduction * - * TagLib is a library for reading and editing audio meta data, commonly know as \e tags. + * TagLib is a library for reading and editing audio meta data, commonly known as \e tags. * * Features: * - A clean, high level, C++ API to handling audio meta data. @@ -109,8 +109,8 @@ namespace TagLib { * TagLib originally was written to provide an updated and improved ID3v2 implementation in C++ for use * in a variety of Open Source projects. Since development began in 2002 and the 1.0 release in 2004 * it has expanded to cover a wide variety of tag and file formats and is used in a wide variety of - * Open Source and proprietary applications. It now supports a variety of UNIXes, including Apple's OS - * X, as well as Microsoft Windows. + * Open Source and proprietary applications. It now supports a variety of UNIXes, including Apple's + * macOS, as well as Microsoft Windows. * * \section commercial Usage in Commercial Applications * @@ -138,15 +138,17 @@ namespace TagLib { * * TagLib provides both simple, abstract APIs which make it possible to ignore the differences between tagging * formats and format specific APIs which allow programmers to work with the features of specific tagging - * schemes. There is a similar abstraction mechanism for AudioProperties. + * schemes. There is a similar abstraction mechanism for \link TagLib::AudioProperties AudioProperties \endlink. * - * The best place to start is with the Class Hierarchy linked at the top of the page. The File and - * AudioProperties classes and their subclasses are the core of TagLib. The FileRef class is also a convenient - * way for using a value-based handle. + * The best place to start is with the Class Hierarchy linked at the top of the page. + * The \link TagLib::File File \endlink and \link TagLib::AudioProperties AudioProperties \endlink + * classes and their subclasses are the core of TagLib. The \link TagLib::FileRef FileRef \endlink + * class is also a convenient way for using a value-based handle. * - * \note When working with FileRef please consider that it has only the most basic (extension-based) file - * type resolution. Please see its documentation on how to plug in more advanced file type resolution. (Such - * resolution may be part of later TagLib releases by default.) + * \note When working with \link TagLib::FileRef FileRef \endlink please consider that it has only + * the most basic (extension-based) file type resolution. Please see its documentation on how to + * plug in more advanced file type resolution. + * (Such resolution may be part of later TagLib releases by default.) * * Here's a very simple example with TagLib: * @@ -186,7 +188,7 @@ namespace TagLib { * f.save(); * \endcode * - * An additional \link FileRef::complexProperties() abstraction \endlink is + * An additional \link TagLib::FileRef::complexProperties() abstraction \endlink is * provided to handle complex (i.e. non textual) properties. * * \code {.cpp} diff --git a/taglib/toolkit/tbytevector.h b/taglib/toolkit/tbytevector.h index 918bbd9f7..4a5b790ca 100644 --- a/taglib/toolkit/tbytevector.h +++ b/taglib/toolkit/tbytevector.h @@ -38,9 +38,9 @@ namespace TagLib { //! A byte vector /*! - * This class provides a byte vector with some methods that are useful for - * tagging purposes. Many of the search functions are tailored to what is - * useful for finding tag related patterns in a data array. + * This class provides an implicitly shared byte vector with some methods that + * are useful for tagging purposes. Many of the search functions are tailored + * to what is useful for finding tag related patterns in a data array. */ class TAGLIB_EXPORT ByteVector @@ -171,12 +171,12 @@ namespace TagLib { unsigned int patternOffset = 0, unsigned int patternLength = 0xffffffff) const; /*! - * Returns true if the vector starts with \a pattern. + * Returns \c true if the vector starts with \a pattern. */ bool startsWith(const ByteVector &pattern) const; /*! - * Returns true if the vector ends with \a pattern. + * Returns \c true if the vector ends with \a pattern. */ bool endsWith(const ByteVector &pattern) const; @@ -282,7 +282,7 @@ namespace TagLib { ConstReverseIterator rend() const; /*! - * Returns true if the ByteVector is empty. + * Returns \c true if the ByteVector is empty. * * \see size() */ @@ -291,9 +291,9 @@ namespace TagLib { /*! * Converts the first 4 bytes of the vector to an unsigned integer. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00 == + * \c true then $00 $00 $00 $01 == 0x00000001 == 1, if \c false, $01 00 00 00 == * 0x01000000 == 1. * * \see fromUInt() @@ -303,9 +303,9 @@ namespace TagLib { /*! * Converts the 4 bytes at \a offset of the vector to an unsigned integer. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00 == + * \c true then $00 $00 $00 $01 == 0x00000001 == 1, if \c false, $01 00 00 00 == * 0x01000000 == 1. * * \see fromUInt() @@ -316,9 +316,9 @@ namespace TagLib { * Converts the \a length bytes at \a offset of the vector to an unsigned * integer. If \a length is larger than 4, the excess is ignored. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00 == + * \c true then $00 $00 $00 $01 == 0x00000001 == 1, if \c false, $01 00 00 00 == * 0x01000000 == 1. * * \see fromUInt() @@ -329,9 +329,9 @@ namespace TagLib { /*! * Converts the first 2 bytes of the vector to a (signed) short. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. + * \c true then $00 $01 == 0x0001 == 1, if \c false, $01 00 == 0x01000000 == 1. * * \see fromShort() */ @@ -340,9 +340,9 @@ namespace TagLib { /*! * Converts the 2 bytes at \a offset of the vector to a (signed) short. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. + * \c true then $00 $01 == 0x0001 == 1, if \c false, $01 00 == 0x01000000 == 1. * * \see fromShort() */ @@ -351,9 +351,9 @@ namespace TagLib { /*! * Converts the first 2 bytes of the vector to an unsigned short. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. + * \c true then $00 $01 == 0x0001 == 1, if \c false, $01 00 == 0x01000000 == 1. * * \see fromUShort() */ @@ -362,9 +362,9 @@ namespace TagLib { /*! * Converts the 2 bytes at \a offset of the vector to an unsigned short. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. + * \c true then $00 $01 == 0x0001 == 1, if \c false, $01 00 == 0x01000000 == 1. * * \see fromUShort() */ @@ -373,10 +373,10 @@ namespace TagLib { /*! * Converts the first 8 bytes of the vector to a (signed) long long. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, - * if false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. + * \c true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, + * if \c false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. * * \see fromLongLong() */ @@ -385,10 +385,10 @@ namespace TagLib { /*! * Converts the 8 bytes at \a offset of the vector to a (signed) long long. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, - * if false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. + * \c true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, + * if \c false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. * * \see fromLongLong() */ @@ -397,10 +397,10 @@ namespace TagLib { /*! * Converts the first 8 bytes of the vector to an unsigned long long. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, - * if false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. + * \c true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, + * if \c false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. * * \see fromULongLong() */ @@ -409,48 +409,56 @@ namespace TagLib { /*! * Converts the 8 bytes at \a offset of the vector to an unsigned long long. * - * If \a mostSignificantByteFirst is true this will operate left to right + * If \a mostSignificantByteFirst is \c true this will operate left to right * evaluating the integer. For example if \a mostSignificantByteFirst is - * true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, - * if false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. + * \c true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, + * if \c false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. * * \see fromULongLong() */ unsigned long long toULongLong(unsigned int offset, bool mostSignificantByteFirst = true) const; - /* + /*! * Converts the 4 bytes at \a offset of the vector to a float as an IEEE754 * 32-bit little-endian floating point number. + * + * \see fromFloat32LE() */ float toFloat32LE(size_t offset) const; - /* + /*! * Converts the 4 bytes at \a offset of the vector to a float as an IEEE754 * 32-bit big-endian floating point number. + * + * \see fromFloat32BE() */ float toFloat32BE(size_t offset) const; - /* + /*! * Converts the 8 bytes at \a offset of the vector to a double as an IEEE754 * 64-bit little-endian floating point number. + * + * \see fromFloat64LE() */ double toFloat64LE(size_t offset) const; - /* + /*! * Converts the 8 bytes at \a offset of the vector to a double as an IEEE754 * 64-bit big-endian floating point number. + * + * \see fromFloat64BE() */ double toFloat64BE(size_t offset) const; - /* - * Converts the 10 bytes at \a offset of the vector to a long double as an - * IEEE754 80-bit little-endian floating point number. - * - * \note This may compromise the precision depends on the size of long double. - */ + /*! + * Converts the 10 bytes at \a offset of the vector to a long double as an + * IEEE754 80-bit little-endian floating point number. + * + * \note This may compromise the precision depends on the size of long double. + */ long double toFloat80LE(size_t offset) const; - /* + /*! * Converts the 10 bytes at \a offset of the vector to a long double as an * IEEE754 80-bit big-endian floating point number. * @@ -460,9 +468,9 @@ namespace TagLib { /*! * Creates a 4 byte ByteVector based on \a value. If - * \a mostSignificantByteFirst is true, then this will operate left to right + * \a mostSignificantByteFirst is \c true, then this will operate left to right * in building the ByteVector. For example if \a mostSignificantByteFirst is - * true then $00 00 00 01 == 0x00000001 == 1, if false, $01 00 00 00 == + * \c true then $00 00 00 01 == 0x00000001 == 1, if \c false, $01 00 00 00 == * 0x01000000 == 1. * * \see toUInt() @@ -471,9 +479,9 @@ namespace TagLib { /*! * Creates a 2 byte ByteVector based on \a value. If - * \a mostSignificantByteFirst is true, then this will operate left to right + * \a mostSignificantByteFirst is \c true, then this will operate left to right * in building the ByteVector. For example if \a mostSignificantByteFirst is - * true then $00 01 == 0x0001 == 1, if false, $01 00 == 0x0100 == 1. + * \c true then $00 01 == 0x0001 == 1, if \c false, $01 00 == 0x0100 == 1. * * \see toShort() */ @@ -481,9 +489,9 @@ namespace TagLib { /*! * Creates a 2 byte ByteVector based on \a value. If - * \a mostSignificantByteFirst is true, then this will operate left to right + * \a mostSignificantByteFirst is \c true, then this will operate left to right * in building the ByteVector. For example if \a mostSignificantByteFirst is - * true then $00 01 == 0x0001 == 1, if false, $01 00 == 0x0100 == 1. + * \c true then $00 01 == 0x0001 == 1, if \c false, $01 00 == 0x0100 == 1. * * \see toUShort() */ @@ -491,9 +499,9 @@ namespace TagLib { /*! * Creates a 8 byte ByteVector based on \a value. If - * \a mostSignificantByteFirst is true, then this will operate left to right + * \a mostSignificantByteFirst is \c true, then this will operate left to right * in building the ByteVector. For example if \a mostSignificantByteFirst is - * true then $00 00 00 01 == 0x0000000000000001 == 1, if false, + * \c true then $00 00 00 01 == 0x0000000000000001 == 1, if \c false, * $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. * * \see toLongLong() @@ -502,9 +510,9 @@ namespace TagLib { /*! * Creates a 8 byte ByteVector based on \a value. If - * \a mostSignificantByteFirst is true, then this will operate left to right + * \a mostSignificantByteFirst is \c true, then this will operate left to right * in building the ByteVector. For example if \a mostSignificantByteFirst is - * true then $00 00 00 01 == 0x0000000000000001 == 1, if false, + * \c true then $00 00 00 01 == 0x0000000000000001 == 1, if \c false, * $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. * * \see toULongLong() @@ -515,7 +523,7 @@ namespace TagLib { * Creates a 4 byte ByteVector based on \a value as an IEEE754 32-bit * little-endian floating point number. * - * \see fromFloat32BE() + * \see toFloat32LE() */ static ByteVector fromFloat32LE(float value); @@ -523,7 +531,7 @@ namespace TagLib { * Creates a 4 byte ByteVector based on \a value as an IEEE754 32-bit * big-endian floating point number. * - * \see fromFloat32LE() + * \see toFloat32BE() */ static ByteVector fromFloat32BE(float value); @@ -531,7 +539,7 @@ namespace TagLib { * Creates a 8 byte ByteVector based on \a value as an IEEE754 64-bit * little-endian floating point number. * - * \see fromFloat64BE() + * \see toFloat64LE() */ static ByteVector fromFloat64LE(double value); @@ -539,7 +547,7 @@ namespace TagLib { * Creates a 8 byte ByteVector based on \a value as an IEEE754 64-bit * big-endian floating point number. * - * \see fromFloat64LE() + * \see toFloat64BE() */ static ByteVector fromFloat64BE(double value); @@ -559,36 +567,36 @@ namespace TagLib { char &operator[](int index); /*! - * Returns true if this ByteVector and \a v are equal. + * Returns \c true if this ByteVector and \a v are equal. */ bool operator==(const ByteVector &v) const; /*! - * Returns true if this ByteVector and \a v are not equal. + * Returns \c true if this ByteVector and \a v are not equal. */ bool operator!=(const ByteVector &v) const; /*! - * Returns true if this ByteVector and the null terminated C string \a s + * Returns \c true if this ByteVector and the null terminated C string \a s * contain the same data. */ bool operator==(const char *s) const; /*! - * Returns true if this ByteVector and the null terminated C string \a s + * Returns \c true if this ByteVector and the null terminated C string \a s * do not contain the same data. */ bool operator!=(const char *s) const; /*! - * Returns true if this ByteVector is less than \a v. The value of the + * Returns \c true if this ByteVector is less than \a v. The value of the * vectors is determined by evaluating the character from left to right, and * in the event one vector is a superset of the other, the size is used. */ bool operator<(const ByteVector &v) const; /*! - * Returns true if this ByteVector is greater than \a v. + * Returns \c true if this ByteVector is greater than \a v. */ bool operator>(const ByteVector &v) const; @@ -615,7 +623,7 @@ namespace TagLib { ByteVector &operator=(const char *data); /*! - * Exchanges the content of the ByteVector by the content of \a v. + * Exchanges the content of the ByteVector with the content of \a v. */ void swap(ByteVector &v) noexcept; @@ -626,16 +634,20 @@ namespace TagLib { /*! * Returns a base64 encoded copy of the byte vector + * + * \see fromBase64() */ ByteVector toBase64() const; /*! * Decodes the base64 encoded byte vector. + * + * \see toBase64() */ static ByteVector fromBase64(const ByteVector &); protected: - /* + /*! * If this ByteVector is being shared via implicit sharing, do a deep copy * of the data and separate from the shared members. This should be called * by all non-const subclass members. diff --git a/taglib/toolkit/tbytevectorstream.cpp b/taglib/toolkit/tbytevectorstream.cpp index 7a142f570..f65f591db 100644 --- a/taglib/toolkit/tbytevectorstream.cpp +++ b/taglib/toolkit/tbytevectorstream.cpp @@ -56,7 +56,7 @@ ByteVectorStream::~ByteVectorStream() = default; FileName ByteVectorStream::name() const { - return ""; // XXX do we need a name? + return ""; } ByteVector ByteVectorStream::readBlock(size_t length) diff --git a/taglib/toolkit/tbytevectorstream.h b/taglib/toolkit/tbytevectorstream.h index 10efe8609..ce33a39d2 100644 --- a/taglib/toolkit/tbytevectorstream.h +++ b/taglib/toolkit/tbytevectorstream.h @@ -43,8 +43,7 @@ namespace TagLib { { public: /*! - * Construct a File object and opens the \a file. \a file should be a - * be a C-string in the local file system encoding. + * Construct a ByteVectorStream from the bytes in \a data. */ ByteVectorStream(const ByteVector &data); @@ -57,7 +56,7 @@ namespace TagLib { ByteVectorStream &operator=(const ByteVectorStream &) = delete; /*! - * Returns the file name in the local file system encoding. + * Returns an empty string. */ FileName name() const override; @@ -67,9 +66,7 @@ namespace TagLib { ByteVector readBlock(size_t length) override; /*! - * Attempts to write the block \a data at the current get pointer. If the - * file is currently only opened read only -- i.e. readOnly() returns true -- - * this attempts to reopen the file in read/write mode. + * Writes the block \a data at the current get pointer. * * \note This should be used instead of using the streaming output operator * for a ByteVector. And even this function is significantly slower than @@ -96,13 +93,12 @@ namespace TagLib { void removeBlock(offset_t start = 0, size_t length = 0) override; /*! - * Returns true if the file is read only (or if the file can not be opened). + * Returns \c false. */ bool readOnly() const override; /*! - * Since the file can currently only be opened as an argument to the - * constructor (sort-of by design), this returns if that open succeeded. + * Returns \c true. */ bool isOpen() const override; @@ -115,7 +111,7 @@ namespace TagLib { void seek(offset_t offset, Position p = Beginning) override; /*! - * Reset the end-of-file and error flags on the file. + * Does nothing. */ void clear() override; diff --git a/taglib/toolkit/tfile.h b/taglib/toolkit/tfile.h index 8347b6b92..5752a82e4 100644 --- a/taglib/toolkit/tfile.h +++ b/taglib/toolkit/tfile.h @@ -164,7 +164,7 @@ namespace TagLib { /*! * Save the file and its associated tags. This should be reimplemented in - * the concrete subclasses. Returns true if the save succeeds. + * the concrete subclasses. Returns \c true if the save succeeds. * * \warning On UNIX multiple processes are able to write to the same file at * the same time. This can result in serious file corruption. If you are @@ -181,7 +181,7 @@ namespace TagLib { /*! * Attempts to write the block \a data at the current get pointer. If the - * file is currently only opened read only -- i.e. readOnly() returns true -- + * file is currently only opened read only -- i.e. readOnly() returns \c true -- * this attempts to reopen the file in read/write mode. * * \note This should be used instead of using the streaming output operator @@ -241,7 +241,7 @@ namespace TagLib { void removeBlock(offset_t start = 0, size_t length = 0); /*! - * Returns true if the file is read only (or if the file can not be opened). + * Returns \c true if the file is read only (or if the file can not be opened). */ bool readOnly() const; @@ -252,7 +252,7 @@ namespace TagLib { bool isOpen() const; /*! - * Returns true if the file is open and readable. + * Returns \c true if the file is open and readable. */ bool isValid() const; @@ -282,7 +282,7 @@ namespace TagLib { protected: /*! * Construct a File object and opens the \a file. \a file should be a - * be a C-string in the local file system encoding. + * C-string in the local file system encoding. * * \note Constructor is protected since this class should only be * instantiated through subclasses. diff --git a/taglib/toolkit/tfilestream.h b/taglib/toolkit/tfilestream.h index 3a7618eb4..3eec56301 100644 --- a/taglib/toolkit/tfilestream.h +++ b/taglib/toolkit/tfilestream.h @@ -37,25 +37,19 @@ namespace TagLib { class Tag; class AudioProperties; - //! A file class with some useful methods for tag manipulation - - /*! - * This class is a basic file class with some methods that are particularly - * useful for tag editors. It has methods to take advantage of - * ByteVector and a binary search method for finding patterns in a file. - */ + //! I/O stream with data from a file. class TAGLIB_EXPORT FileStream : public IOStream { public: /*! - * Construct a File object and opens the \a file. \a file should be a - * be a C-string in the local file system encoding. + * Construct a FileStream object and opens the \a file. \a file should be a + * C-string in the local file system encoding. */ FileStream(FileName file, bool openReadOnly = false); /*! - * Construct a File object and opens the \a file using file descriptor. + * Construct a FileStream object using an existing \a fileDescriptor. */ FileStream(int fileDescriptor, bool openReadOnly = false); @@ -79,7 +73,7 @@ namespace TagLib { /*! * Attempts to write the block \a data at the current get pointer. If the - * file is currently only opened read only -- i.e. readOnly() returns true -- + * file is currently only opened read only -- i.e. readOnly() returns \c true -- * this attempts to reopen the file in read/write mode. * * \note This should be used instead of using the streaming output operator @@ -107,7 +101,7 @@ namespace TagLib { void removeBlock(offset_t start = 0, size_t length = 0) override; /*! - * Returns true if the file is read only (or if the file can not be opened). + * Returns \c true if the file is read only (or if the file can not be opened). */ bool readOnly() const override; diff --git a/taglib/toolkit/tiostream.h b/taglib/toolkit/tiostream.h index 6d9698b43..29609b348 100644 --- a/taglib/toolkit/tiostream.h +++ b/taglib/toolkit/tiostream.h @@ -94,7 +94,7 @@ namespace TagLib { /*! * Attempts to write the block \a data at the current get pointer. If the - * file is currently only opened read only -- i.e. readOnly() returns true -- + * file is currently only opened read only -- i.e. readOnly() returns \c true -- * this attempts to reopen the file in read/write mode. * * \note This should be used instead of using the streaming output operator @@ -123,7 +123,7 @@ namespace TagLib { virtual void removeBlock(offset_t start = 0, size_t length = 0) = 0; /*! - * Returns true if the file is read only (or if the file can not be opened). + * Returns \c true if the file is read only (or if the file can not be opened). */ virtual bool readOnly() const = 0; diff --git a/taglib/toolkit/tlist.h b/taglib/toolkit/tlist.h index 6f0273e60..9e0707103 100644 --- a/taglib/toolkit/tlist.h +++ b/taglib/toolkit/tlist.h @@ -37,8 +37,8 @@ namespace TagLib { //! A generic, implicitly shared list. /*! - * This is basic generic list that's somewhere between a std::list and a - * QValueList. This class is implicitly shared. For example: + * This is a basic generic list that's somewhere between a std::list and a + * QList. This class is implicitly shared. For example: * * \code * @@ -46,7 +46,7 @@ namespace TagLib { * * \endcode * - * The above example is very cheap. This also makes lists suitable for the + * The above example is very cheap. This also makes lists suitable as * return types of functions. The above example will just copy a pointer rather * than copying the data in the list. When your \e shared list's data changes, * only \e then will the data be copied. @@ -85,37 +85,37 @@ namespace TagLib { /*! * Returns an STL style iterator to the beginning of the list. See - * std::list::const_iterator for the semantics. + * \c std::list::const_iterator for the semantics. */ Iterator begin(); /*! * Returns an STL style constant iterator to the beginning of the list. See - * std::list::iterator for the semantics. + * \c std::list::iterator for the semantics. */ ConstIterator begin() const; /*! * Returns an STL style constant iterator to the beginning of the list. See - * std::list::iterator for the semantics. + * \c std::list::iterator for the semantics. */ ConstIterator cbegin() const; /*! * Returns an STL style iterator to the end of the list. See - * std::list::iterator for the semantics. + * \c std::list::iterator for the semantics. */ Iterator end(); /*! * Returns an STL style constant iterator to the end of the list. See - * std::list::const_iterator for the semantics. + * \c std::list::const_iterator for the semantics. */ ConstIterator end() const; /*! * Returns an STL style constant iterator to the end of the list. See - * std::list::const_iterator for the semantics. + * \c std::list::const_iterator for the semantics. */ ConstIterator cend() const; @@ -130,7 +130,7 @@ namespace TagLib { /*! * Inserts the \a value into the list. This assumes that the list is - * currently sorted. If \a unique is true then the value will not + * currently sorted. If \a unique is \c true then the value will not * be inserted if it is already in the list. */ List &sortedInsert(const T &value, bool unique = false); @@ -197,7 +197,7 @@ namespace TagLib { ConstIterator cfind(const T &value) const; /*! - * Returns true if the list contains \a value. + * Returns \c true if the list contains \a value. */ bool contains(const T &value) const; @@ -241,7 +241,7 @@ namespace TagLib { void setAutoDelete(bool autoDelete); /*! - * Returns true is auto-deletion is enabled. + * Returns \c true is auto-deletion is enabled. */ bool autoDelete() const; @@ -274,18 +274,18 @@ namespace TagLib { List &operator=(std::initializer_list init); /*! - * Exchanges the content of this list by the content of \a l. + * Exchanges the content of this list with the content of \a l. */ void swap(List &l) noexcept; /*! - * Compares this list with \a l and returns true if all of the elements are + * Compares this list with \a l and returns \c true if all of the elements are * the same. */ bool operator==(const List &l) const; /*! - * Compares this list with \a l and returns true if the lists differ. + * Compares this list with \a l and returns \c true if the lists differ. */ bool operator!=(const List &l) const; @@ -296,14 +296,14 @@ namespace TagLib { /*! * Sorts this list in ascending order using the comparison - * function object \a comp which returns true if the first argument is + * function object \a comp which returns \c true if the first argument is * less than the second. */ template void sort(Compare&& comp); protected: - /* + /*! * If this List is being shared via implicit sharing, do a deep copy of the * data and separate from the shared members. This should be called by all * non-const subclass members without Iterator parameters. diff --git a/taglib/toolkit/tmap.h b/taglib/toolkit/tmap.h index 8404a10dc..b6df8d58b 100644 --- a/taglib/toolkit/tmap.h +++ b/taglib/toolkit/tmap.h @@ -88,37 +88,37 @@ namespace TagLib { /*! * Returns an STL style iterator to the beginning of the map. See - * std::map::iterator for the semantics. + * \c std::map::iterator for the semantics. */ Iterator begin(); /*! * Returns an STL style iterator to the beginning of the map. See - * std::map::const_iterator for the semantics. + * \c std::map::const_iterator for the semantics. */ ConstIterator begin() const; /*! * Returns an STL style iterator to the beginning of the map. See - * std::map::const_iterator for the semantics. + * \c std::map::const_iterator for the semantics. */ ConstIterator cbegin() const; /*! * Returns an STL style iterator to the end of the map. See - * std::map::iterator for the semantics. + * \c std::map::iterator for the semantics. */ Iterator end(); /*! * Returns an STL style iterator to the end of the map. See - * std::map::const_iterator for the semantics. + * \c std::map::const_iterator for the semantics. */ ConstIterator end() const; /*! * Returns an STL style iterator to the end of the map. See - * std::map::const_iterator for the semantics. + * \c std::map::const_iterator for the semantics. */ ConstIterator cend() const; @@ -129,7 +129,7 @@ namespace TagLib { Map &insert(const Key &key, const T &value); /*! - * Removes all of the elements from elements from the map. This however + * Removes all of the elements from the map. This however * will not delete pointers if the mapped type is a pointer type. */ Map &clear(); @@ -142,7 +142,7 @@ namespace TagLib { unsigned int size() const; /*! - * Returns true if the map is empty. + * Returns \c true if the map is empty. * * \see size() */ @@ -159,7 +159,7 @@ namespace TagLib { ConstIterator find(const Key &key) const; /*! - * Returns true if the map contains an instance of \a key. + * Returns \c true if the map contains an item for \a key. */ bool contains(const Key &key) const; @@ -180,8 +180,8 @@ namespace TagLib { /*! * Returns the value associated with \a key. * - * If the map does not contain \a key, it returns defaultValue. - * If no defaultValue is specified, it returns a default-constructed value. + * If the map does not contain \a key, it returns \a defaultValue. + * If no \a defaultValue is specified, it returns a default-constructed value. */ T value(const Key &key, const T &defaultValue = T()) const; @@ -212,23 +212,23 @@ namespace TagLib { Map &operator=(std::initializer_list> init); /*! - * Exchanges the content of this map by the content of \a m. + * Exchanges the content of this map with the content of \a m. */ void swap(Map &m) noexcept; /*! - * Compares this map with \a m and returns true if all of the elements are + * Compares this map with \a m and returns \c true if all of the elements are * the same. */ bool operator==(const Map &m) const; /*! - * Compares this map with \a m and returns true if the maps differ. + * Compares this map with \a m and returns \c true if the maps differ. */ bool operator!=(const Map &m) const; protected: - /* + /*! * If this Map is being shared via implicit sharing, do a deep copy of the * data and separate from the shared members. This should be called by all * non-const subclass members without Iterator parameters. diff --git a/taglib/toolkit/tpropertymap.h b/taglib/toolkit/tpropertymap.h index 5f2768228..0cc4486b2 100644 --- a/taglib/toolkit/tpropertymap.h +++ b/taglib/toolkit/tpropertymap.h @@ -38,7 +38,7 @@ namespace TagLib { using SimplePropertyMap = Map; - //! A map for format-independent tag representations. + //! A map for format-independent tag representations. /*! * This map implements a generic representation of textual audio metadata @@ -175,13 +175,13 @@ namespace TagLib { ConstIterator find(const String &key) const; /*! - * Returns true if the map contains values for \a key. + * Returns \c true if the map contains values for \a key. */ TAGLIB_EXPORT bool contains(const String &key) const; /*! - * Returns true if this map contains all keys of \a other + * Returns \c true if this map contains all keys of \a other * and the values coincide for that keys. Does not take * the unsupportedData list into account. */ @@ -212,8 +212,8 @@ namespace TagLib { /*! * Returns the value associated with \a key. * - * If the map does not contain \a key, it returns defaultValue. - * If no defaultValue is specified, it returns an empty string list. + * If the map does not contain \a key, it returns \a defaultValue. + * If no \a defaultValue is specified, it returns an empty string list. */ TAGLIB_EXPORT StringList value(const String &key, @@ -222,7 +222,7 @@ namespace TagLib { /*! * Returns a reference to the value associated with \a key. * - * \note: If \a key is not contained in the map, an empty + * \note If \a key is not contained in the map, an empty * StringList is returned without error. */ TAGLIB_EXPORT @@ -231,7 +231,7 @@ namespace TagLib { /*! * Returns a reference to the value associated with \a key. * - * \note: If \a key is not contained in the map, an empty + * \note If \a key is not contained in the map, an empty * StringList is returned. You can also directly add entries * by using this function as an lvalue. */ @@ -239,25 +239,26 @@ namespace TagLib { StringList &operator[](const String &key); /*! - * Returns true if and only if \a other has the same contents as this map. + * Returns \c true if and only if \a other has the same contents as this map. */ TAGLIB_EXPORT bool operator==(const PropertyMap &other) const; /*! - * Returns false if and only \a other has the same contents as this map. + * Returns \c false if and only if \a other has the same contents as this map. */ TAGLIB_EXPORT bool operator!=(const PropertyMap &other) const; /*! - * If a PropertyMap is read from a File object using File::properties(), + * If a PropertyMap is read from a File object using File::properties() + * (or a FileRef object using FileRef::properties()), * the StringList returned from this function will represent metadata * that could not be parsed into the PropertyMap representation. This could * be e.g. binary data, unknown ID3 frames, etc. - * You can remove items from the returned list, which tells TagLib to remove - * those unsupported elements if you call File::setProperties() with the - * same PropertyMap as argument. + * + * \see File::removeUnsupportedProperties(), + * FileRef::removeUnsupportedProperties() */ TAGLIB_EXPORT const StringList &unsupportedData() const; diff --git a/taglib/toolkit/tstring.h b/taglib/toolkit/tstring.h index 78abe3ec8..070013c24 100644 --- a/taglib/toolkit/tstring.h +++ b/taglib/toolkit/tstring.h @@ -69,16 +69,16 @@ namespace TagLib { /*! * This is an implicitly shared \e wide string. For storage it uses * TagLib::wstring, but as this is an implementation detail this of - * course could change. Strings are stored internally as UTF-16(without BOM/ - * CPU byte order) + * course could change. Strings are stored internally as UTF-16 (without + * BOM/CPU byte order) * * The use of implicit sharing means that copying a string is cheap, the only * \e cost comes into play when the copy is modified. Prior to that the string * just has a pointer to the data of the \e parent String. This also makes * this class suitable as a function return type. * - * In addition to adding implicit sharing, this class keeps track of four - * possible encodings, which are the four supported by the ID3v2 standard. + * In addition to adding implicit sharing, this class keeps track of + * possible encodings, which are those supported by the ID3v2 standard. */ class TAGLIB_EXPORT String @@ -92,6 +92,7 @@ namespace TagLib { /** * The four types of string encodings supported by the ID3v2 specification. + * (plus UTF16LE). * ID3v1 is assumed to be Latin1 and Ogg Vorbis comments use UTF8. */ enum Type { @@ -190,8 +191,8 @@ namespace TagLib { ~String(); /*! - * Returns a deep copy of this String as an std::string. The returned string - * is encoded in UTF8 if \a unicode is true, otherwise Latin1. + * Returns a deep copy of this String as an \c std::string. The returned string + * is encoded in UTF8 if \a unicode is \c true, otherwise Latin1. * * \see toCString() */ @@ -199,7 +200,7 @@ namespace TagLib { /*! * Returns a deep copy of this String as a wstring. The returned string is - * encoded in UTF-16 (without BOM/CPU byte order), not UTF-32 even if wchar_t + * encoded in UTF-16 (without BOM/CPU byte order), not UTF-32 even if \c wchar_t * is 32-bit wide. * * \see toCWString() @@ -208,7 +209,7 @@ namespace TagLib { /*! * Creates and returns a standard C-style (null-terminated) version of this - * String. The returned string is encoded in UTF8 if \a unicode is true, + * String. The returned string is encoded in UTF8 if \a unicode is \c true, * otherwise Latin1. * * The returned string is still owned by this String and should not be deleted @@ -229,7 +230,7 @@ namespace TagLib { /*! * Returns a standard C-style (null-terminated) wide character version of * this String. The returned string is encoded in UTF-16 (without BOM/CPU byte - * order), not UTF-32 even if wchar_t is 32-bit wide. + * order), not UTF-32 even if \c wchar_t is 32-bit wide. * * The returned string is still owned by this String and should not be deleted * by the user. @@ -296,7 +297,7 @@ namespace TagLib { StringList split(const String &separator = " ") const; /*! - * Returns true if the strings starts with the substring \a s. + * Returns \c true if the strings starts with the substring \a s. */ bool startsWith(const String &s) const; @@ -335,7 +336,7 @@ namespace TagLib { unsigned int length() const; /*! - * Returns true if the string is empty. + * Returns \c true if the string is empty. */ bool isEmpty() const; @@ -355,7 +356,7 @@ namespace TagLib { * Convert the string to an integer. * * If the conversion was successful, it sets the value of \a *ok to - * true and returns the integer. Otherwise it sets \a *ok to false + * \c true and returns the integer. Otherwise it sets \a *ok to \c false * and the result is undefined. */ int toInt(bool *ok = nullptr) const; @@ -366,12 +367,12 @@ namespace TagLib { String stripWhiteSpace() const; /*! - * Returns true if the file only uses characters required by Latin1. + * Returns \c true if the file only uses characters required by Latin1. */ bool isLatin1() const; /*! - * Returns true if the file only uses characters required by (7-bit) ASCII. + * Returns \c true if the file only uses characters required by (7-bit) ASCII. */ bool isAscii() const; @@ -397,37 +398,37 @@ namespace TagLib { /*! * Compares each character of the String with each character of \a s and - * returns true if the strings match. + * returns \c true if the strings match. */ bool operator==(const String &s) const; /*! * Compares each character of the String with each character of \a s and - * returns false if the strings match. + * returns \c false if the strings match. */ bool operator!=(const String &s) const; /*! * Compares each character of the String with each character of \a s and - * returns true if the strings match. + * returns \c true if the strings match. */ bool operator==(const char *s) const; /*! * Compares each character of the String with each character of \a s and - * returns false if the strings match. + * returns \c false if the strings match. */ bool operator!=(const char *s) const; /*! * Compares each character of the String with each character of \a s and - * returns true if the strings match. + * returns \c true if the strings match. */ bool operator==(const wchar_t *s) const; /*! * Compares each character of the String with each character of \a s and - * returns false if the strings match. + * returns \c false if the strings match. */ bool operator!=(const wchar_t *s) const; @@ -498,13 +499,13 @@ namespace TagLib { String &operator=(const ByteVector &v); /*! - * Exchanges the content of the String by the content of \a s. + * Exchanges the content of the String with the content of \a s. */ void swap(String &s) noexcept; /*! * To be able to use this class in a Map, this operator needed to be - * implemented. Returns true if \a s is less than this string in a byte-wise + * implemented. Returns \c true if \a s is less than this string in a byte-wise * comparison. */ bool operator<(const String &s) const; diff --git a/taglib/toolkit/tstringlist.h b/taglib/toolkit/tstringlist.h index 31f19dc2f..2c5997974 100644 --- a/taglib/toolkit/tstringlist.h +++ b/taglib/toolkit/tstringlist.h @@ -38,8 +38,8 @@ namespace TagLib { //! A list of strings /*! - * This is a specialization of the List class with some members convention for - * string operations. + * This is a specialization of the List class with some convenience members + * for string operations. */ class StringList : public List diff --git a/taglib/toolkit/tvariant.h b/taglib/toolkit/tvariant.h index bfbe18282..f814fc0fc 100644 --- a/taglib/toolkit/tvariant.h +++ b/taglib/toolkit/tvariant.h @@ -50,6 +50,8 @@ namespace TagLib { class ByteVector; class ByteVectorList; + //! An implicitly shared discriminated union. + /*! * This is an implicitly shared discriminated union. * @@ -65,19 +67,19 @@ namespace TagLib { // The number and order of these types must correspond to the template // parameters for StdVariantType in tvariant.cpp! enum Type { - Void, - Bool, - Int, - UInt, - LongLong, - ULongLong, - Double, - String, - StringList, - ByteVector, - ByteVectorList, - VariantList, - VariantMap + Void, //!< variant is empty + Bool, //!< \c bool + Int, //!< \c int + UInt, //!< unsigned int + LongLong, //!< long long + ULongLong, //!< unsigned long long + Double, //!< \c double + String, //!< String + StringList, //!< StringList + ByteVector, //!< ByteVector + ByteVectorList, //!< ByteVectorList + VariantList, //!< \link TagLib::VariantList VariantList \endlink + VariantMap //!< \link TagLib::VariantMap VariantMap \endlink }; /*! @@ -85,11 +87,7 @@ namespace TagLib { */ Variant(); - /*! - * Constructs a Variant from an integer value. - */ Variant(int val); - Variant(unsigned int val); Variant(long long val); Variant(unsigned long long val); @@ -121,49 +119,60 @@ namespace TagLib { Type type() const; /*! - * Returns true if the Variant is empty. + * Returns \c true if the Variant is empty. */ bool isEmpty() const; /*! - * Extracts an integer value from the Variant. - * If \a ok is passed, its boolean variable will be set to true if the + * Extracts a value from the Variant. + * If \a ok is passed, its boolean variable will be set to \c true if the * Variant contains the correct type, and the returned value is the value - * of the Variant. Otherwise, the \a ok variable is set to false and + * of the Variant. Otherwise, the \a ok variable is set to \c false and * a dummy default value is returned. */ int toInt(bool *ok = nullptr) const; + //! \copydoc toInt() unsigned int toUInt(bool *ok = nullptr) const; + //! \copydoc toInt() long long toLongLong(bool *ok = nullptr) const; + //! \copydoc toInt() unsigned long long toULongLong(bool *ok = nullptr) const; + //! \copydoc toInt() bool toBool(bool *ok = nullptr) const; + //! \copydoc toInt() double toDouble(bool *ok = nullptr) const; + //! \copydoc toInt() TagLib::String toString(bool *ok = nullptr) const; + //! \copydoc toInt() TagLib::StringList toStringList(bool *ok = nullptr) const; + //! \copydoc toInt() TagLib::ByteVector toByteVector(bool *ok = nullptr) const; + //! \copydoc toInt() TagLib::ByteVectorList toByteVectorList(bool *ok = nullptr) const; + //! \copydoc toInt() TagLib::List toList(bool *ok = nullptr) const; + //! \copydoc toInt() TagLib::Map toMap(bool *ok = nullptr) const; /*! * Extracts value of type \a T from the Variant. - * If \a ok is passed, its boolean variable will be set to true if the + * If \a ok is passed, its boolean variable will be set to \c true if the * Variant contains the correct type, and the returned value is the value - * of the Variant. Otherwise, the \a ok variable is set to false and + * of the Variant. Otherwise, the \a ok variable is set to \c false and * a dummy default value is returned. */ template T value(bool *ok = nullptr) const; /*! - * Returns true it the Variant and \a v are of the same type and contain the + * Returns \c true it the Variant and \a v are of the same type and contain the * same value. */ bool operator==(const Variant &v) const; /*! - * Returns true it the Variant and \a v differ in type or value. + * Returns \c true it the Variant and \a v differ in type or value. */ bool operator!=(const Variant &v) const; diff --git a/taglib/toolkit/tversionnumber.h b/taglib/toolkit/tversionnumber.h index 9b112fba2..5d61673a7 100644 --- a/taglib/toolkit/tversionnumber.h +++ b/taglib/toolkit/tversionnumber.h @@ -35,9 +35,8 @@ namespace TagLib { class String; - /*! - * Version number with major, minor and patch segments. - */ + //! Version number with major, minor and patch segments. + class TAGLIB_EXPORT VersionNumber { public: /*! @@ -80,42 +79,42 @@ namespace TagLib { } /*! - * Returns true if this version is equal to \a rhs. + * Returns \c true if this version is equal to \a rhs. */ constexpr bool operator==(const VersionNumber &rhs) const { return m_combined == rhs.m_combined; } /*! - * Returns true if this version is not equal to \a rhs. + * Returns \c true if this version is not equal to \a rhs. */ constexpr bool operator!=(const VersionNumber &rhs) const { return m_combined != rhs.m_combined; } /*! - * Returns true if this version is less than \a rhs. + * Returns \c true if this version is less than \a rhs. */ constexpr bool operator<(const VersionNumber &rhs) const { return m_combined < rhs.m_combined; } /*! - * Returns true if this version is greater than \a rhs. + * Returns \c true if this version is greater than \a rhs. */ constexpr bool operator>(const VersionNumber &rhs) const { return m_combined > rhs.m_combined; } /*! - * Returns true if this version is less or equal than \a rhs. + * Returns \c true if this version is less or equal than \a rhs. */ constexpr bool operator<=(const VersionNumber &rhs) const { return m_combined <= rhs.m_combined; } /*! - * Returns true if this version is greater or equal than \a rhs. + * Returns \c true if this version is greater or equal than \a rhs. */ constexpr bool operator>=(const VersionNumber &rhs) const { return m_combined >= rhs.m_combined; diff --git a/taglib/trueaudio/trueaudiofile.h b/taglib/trueaudio/trueaudiofile.h index d0b7f9672..62b3685c9 100644 --- a/taglib/trueaudio/trueaudiofile.h +++ b/taglib/trueaudio/trueaudiofile.h @@ -44,7 +44,7 @@ namespace TagLib { //! An implementation of TrueAudio metadata /*! - * This is implementation of TrueAudio metadata. + * this is an implementation of TrueAudio metadata. * * This supports ID3v1 and ID3v2 tags as well as reading stream * properties from the file. @@ -80,7 +80,7 @@ namespace TagLib { }; /*! - * Constructs a TrueAudio file from \a file. If \a readProperties is true + * Constructs a TrueAudio file from \a file. If \a readProperties is \c true * the file's audio properties will also be read. * * If this file contains an ID3v2 tag, the frames will be created using @@ -93,13 +93,15 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs a TrueAudio file from \a file. If \a readProperties is true + * Constructs a TrueAudio file from \a file. If \a readProperties is \c true * the file's audio properties will also be read. * * If this file contains an ID3v2 tag, the frames will be created using * \a frameFactory. * * \note In the current implementation, \a propertiesStyle is ignored. + * + * \deprecated Use the constructor above. */ TAGLIB_DEPRECATED File(FileName file, ID3v2::FrameFactory *frameFactory, @@ -107,7 +109,7 @@ namespace TagLib { Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs a TrueAudio file from \a stream. If \a readProperties is true + * Constructs a TrueAudio file from \a stream. If \a readProperties is \c true * the file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -123,7 +125,7 @@ namespace TagLib { ID3v2::FrameFactory *frameFactory = nullptr); /*! - * Constructs a TrueAudio file from \a stream. If \a readProperties is true + * Constructs a TrueAudio file from \a stream. If \a readProperties is \c true * the file's audio properties will also be read. * * \note TagLib will *not* take ownership of the stream, the caller is @@ -133,6 +135,8 @@ namespace TagLib { * \a frameFactory. * * \note In the current implementation, \a propertiesStyle is ignored. + * + * \deprecated Use the constructor above. */ TAGLIB_DEPRECATED File(IOStream *stream, ID3v2::FrameFactory *frameFactory, @@ -182,15 +186,15 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid ID3v1 tag. If \a create is \c true it will create * an ID3v1 tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file * on disk actually has an ID3v1 tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the TrueAudio::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * @@ -201,15 +205,15 @@ namespace TagLib { /*! * Returns a pointer to the ID3v2 tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid ID3v2 tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid ID3v2 tag. If \a create is \c true it will create * an ID3v2 tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file * on disk actually has an ID3v2 tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the TrueAudio::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * diff --git a/taglib/wavpack/wavpackfile.h b/taglib/wavpack/wavpackfile.h index 779287a2b..c9e82e6bd 100644 --- a/taglib/wavpack/wavpackfile.h +++ b/taglib/wavpack/wavpackfile.h @@ -44,7 +44,7 @@ namespace TagLib { //! An implementation of WavPack metadata /*! - * This is implementation of WavPack metadata. + * this is an implementation of WavPack metadata. * * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream * properties from the file. @@ -80,17 +80,17 @@ namespace TagLib { }; /*! - * Constructs a WavPack file from \a file. If \a readProperties is true the + * Constructs a WavPack file from \a file. If \a readProperties is \c true the * file's audio properties will also be read using \a propertiesStyle. If - * false, \a propertiesStyle is ignored + * \c false, \a propertiesStyle is ignored */ File(FileName file, bool readProperties = true, Properties::ReadStyle propertiesStyle = Properties::Average); /*! - * Constructs an WavPack file from \a file. If \a readProperties is true the + * Constructs an WavPack file from \a file. If \a readProperties is \c true the * file's audio properties will also be read using \a propertiesStyle. If - * false, \a propertiesStyle is ignored. + * \c false, \a propertiesStyle is ignored. * * \note TagLib will *not* take ownership of the stream, the caller is * responsible for deleting it after the File object. @@ -137,22 +137,22 @@ namespace TagLib { /*! * Saves the file. * - * This returns true if the save was successful. + * This returns \c true if the save was successful. */ bool save() override; /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid ID3v1 tag. If \a create is \c true it will create * an ID3v1 tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file * on disk actually has an ID3v1 tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the WavPack::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * @@ -163,15 +163,15 @@ namespace TagLib { /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this may return a null pointer - * if there is no valid APE tag. If \a create is true it will create + * If \a create is \c false (the default) this may return a null pointer + * if there is no valid APE tag. If \a create is \c true it will create * an APE tag if one does not exist and returns a valid pointer. * * \note This may return a valid pointer regardless of whether or not the * file on disk has an APE tag. Use hasAPETag() to check if the file * on disk actually has an APE tag. * - * \note The Tag is still owned by the MPEG::File and should not be + * \note The Tag is still owned by the WavPack::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. * diff --git a/taglib/xm/xmfile.h b/taglib/xm/xmfile.h index b365e9a3a..b0cd55e28 100644 --- a/taglib/xm/xmfile.h +++ b/taglib/xm/xmfile.h @@ -35,8 +35,23 @@ namespace TagLib { + //! An implementation of Extended Module metadata + + /*! + * this is an implementation of Extended Module metadata. + */ + namespace XM { + //! An implementation of TagLib::File with XM specific methods + + /*! + * This implements and provides an interface for XM files to the + * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing + * the abstract TagLib::File API as well as providing some additional + * information specific to XM files. + */ + class TAGLIB_EXPORT File : public Mod::FileBase { public: /*! diff --git a/taglib/xm/xmproperties.h b/taglib/xm/xmproperties.h index cca58da2a..8b03b3f68 100644 --- a/taglib/xm/xmproperties.h +++ b/taglib/xm/xmproperties.h @@ -32,6 +32,7 @@ namespace TagLib { namespace XM { + //! An implementation of audio property reading for XM class TAGLIB_EXPORT Properties : public AudioProperties { public: /*! Flag bits. */