mirror/taglib
1
0
Fork 0
mirror of https://github.com/taglib/taglib.git synced 2025-06-04 01:28:21 -04:00
Code Issues Packages Projects Releases Wiki Activity

Correct the API documentation

Browse Source
This commit is contained in:
Urs Fleisch 2024-01-01 17:46:45 +01:00
parent ef013b76db
commit c5d798a50d
89 changed files with 728 additions and 541 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
Doxyfile.cmake
View File

@ -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

3
bindings/README
View File

@ -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

2
bindings/c/tag_c.h
View File

@ -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.
*/

18
taglib/ape/apefile.h
View File

@ -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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> 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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> owned by the APE::File and should not be
* deleted by the user. It will be deleted when the file (object) is
* destroyed.
*

10
taglib/ape/apefooter.h
View File

@ -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;

8
taglib/ape/apeitem.h
View File

@ -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;

5
taglib/ape/apetag.h
View File

@ -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;

4
taglib/asf/asfattribute.h
View File

@ -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;

4
taglib/asf/asffile.h
View File

@ -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;

8
taglib/asf/asfpicture.h
View File

@ -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 <tt>const char *</tt> which
* should make it easy to export this data to external programs.
*
* \see setPicture()

14
taglib/asf/asftag.h
View File

@ -39,6 +39,8 @@ namespace TagLib {
using AttributeList = List<Attribute>;
using AttributeListMap = Map<String, AttributeList>;
//! 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;

25
taglib/dsdiff/dsdifffile.h
View File

@ -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
* <a href="https://dsd-guide.com/sites/default/files/white-papers/DSDIFF_1.5_Spec.pdf">
* DSDIFF_1.5_Spec.pdf</a>.
* 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.

2
taglib/dsf/dsffile.cpp
View File

@ -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:

22
taglib/dsf/dsffile.h
View File

@ -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;

1
taglib/dsf/dsfproperties.h
View File

@ -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);

101
taglib/fileref.h
View File

@ -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<FileTypeResolverPrivate> 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;

36
taglib/flac/flacfile.h
View File

@ -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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> 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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> 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<Picture *> 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);

1
taglib/flac/flacmetadatablock.h
View File

@ -32,6 +32,7 @@
namespace TagLib {
namespace FLAC {
//! FLAC metadata block
class TAGLIB_EXPORT MetadataBlock
{
public:

3
taglib/flac/flacpicture.h
View File

@ -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)

1
taglib/flac/flacunknownmetadatablock.h
View File

@ -33,6 +33,7 @@
namespace TagLib {
namespace FLAC {
//! Unknown FLAC metadata block
class TAGLIB_EXPORT UnknownMetadataBlock : public MetadataBlock
{
public:

15
taglib/it/itfile.h
View File

@ -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:
/*!

1
taglib/it/itproperties.h
View File

@ -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. */

17
taglib/mod/modfile.h
View File

@ -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:

1
taglib/mod/modfilebase.h
View File

@ -36,6 +36,7 @@
namespace TagLib {
namespace Mod {
//! Base class for module files
class TAGLIB_EXPORT FileBase : public TagLib::File
{
public:

1
taglib/mod/modproperties.h
View File

@ -31,6 +31,7 @@
namespace TagLib {
namespace Mod {
//! An implementation of audio property reading for Mod
class TAGLIB_EXPORT Properties : public AudioProperties
{
public:

21
taglib/mod/modtag.h
View File

@ -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.

10
taglib/mp4/mp4atom.h
View File

@ -33,12 +33,8 @@
#include "tfile.h"
#include "tlist.h"
#ifndef DO_NOT_DOCUMENT
namespace TagLib {
namespace MP4 {
class Atom;
using AtomList = TagLib::List<Atom *>;
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<Atom *>;
using AtomDataList = TagLib::List<AtomData>;
class TAGLIB_EXPORT Atom
@ -116,9 +115,8 @@ namespace TagLib {
TAGLIB_MSVC_SUPPRESS_WARNING_NEEDS_TO_HAVE_DLL_INTERFACE
std::unique_ptr<AtomsPrivate> d;
};
#endif // DO_NOT_DOCUMENT
} // namespace MP4
} // namespace TagLib
#endif
#endif

3
taglib/mp4/mp4coverart.h
View File

@ -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;

9
taglib/mp4/mp4file.h
View File

@ -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.

3
taglib/mp4/mp4item.h
View File

@ -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;

3
taglib/mp4/mp4tag.h
View File

@ -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;

20
taglib/mpc/mpcfile.h
View File

@ -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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> 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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> owned by the MPC::File and should not be
* deleted by the user. It will be deleted when the file (object) is
* destroyed.
*

2
taglib/mpc/mpcproperties.h
View File

@ -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);

2
taglib/mpeg/id3v1/id3v1tag.h
View File

@ -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

6
taglib/mpeg/id3v2/frames/attachedpictureframe.h
View File

@ -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 <tt>const char *</tt> which
* should make it easy to export this data to external programs.
*
* \see setPicture()

12
taglib/mpeg/id3v2/frames/chapterframe.h
View File

@ -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()

2
taglib/mpeg/id3v2/frames/eventtimingcodesframe.h
View File

@ -137,7 +137,7 @@ namespace TagLib {
EventTimingCodesFrame &operator=(const EventTimingCodesFrame &) = delete;
/*!
* Returns a null string.
* Returns an empty string.
*/
String toString() const override;

2
taglib/mpeg/id3v2/frames/generalencapsulatedobjectframe.h
View File

@ -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 <tt>const char *</tt> which
* should make it easy to export this data to external programs.
*
* \see setObject()

2
taglib/mpeg/id3v2/frames/ownershipframe.cpp
View File

@ -127,7 +127,7 @@ void OwnershipFrame::parseFields(const ByteVector &data)
d->textEncoding = static_cast<String::Type>(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

2
taglib/mpeg/id3v2/frames/ownershipframe.h
View File

@ -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);

2
taglib/mpeg/id3v2/frames/podcastframe.h
View File

@ -56,7 +56,7 @@ namespace TagLib {
PodcastFrame &operator=(const PodcastFrame &) = delete;
/*!
* Returns a null string.
* Returns an empty string.
*/
String toString() const override;

2
taglib/mpeg/id3v2/frames/privateframe.h
View File

@ -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
{

14
taglib/mpeg/id3v2/frames/tableofcontentsframe.h
View File

@ -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()

4
taglib/mpeg/id3v2/frames/textidentificationframe.h
View File

@ -59,7 +59,7 @@ namespace TagLib {
* <li><b>TDTG</b> Tagging time</li>
* <li><b>TENC</b> Encoded by</li>
* <li><b>TEXT</b> Lyricist/Text writer</li>
* <li><b>TFLT</b> File type</li>
* <li><b>TFLT</b> %File type</li>
* <li><b>TIPL</b> Involved people list</li>
* <li><b>TIT1</b> Content group description</li>
* <li><b>TIT2</b> Title/songname/content description</li>
@ -74,7 +74,7 @@ namespace TagLib {
* <li><b>TOFN</b> Original filename</li>
* <li><b>TOLY</b> Original lyricist(s)/text writer(s)</li>
* <li><b>TOPE</b> Original artist(s)/performer(s)</li>
* <li><b>TOWN</b> File owner/licensee</li>
* <li><b>TOWN</b> %File owner/licensee</li>
* <li><b>TPE1</b> Lead performer(s)/Soloist(s)</li>
* <li><b>TPE2</b> Band/orchestra/accompaniment</li>
* <li><b>TPE3</b> Conductor/performer refinement</li>

2
taglib/mpeg/id3v2/frames/unknownframe.h
View File

@ -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.
*

10
taglib/mpeg/id3v2/id3v2.h
View File

@ -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
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.2.0.txt">
* id3v2.2.0.txt</a>
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.3.0.txt">
* id3v2.3.0.txt</a>
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>
*
* \see ID3v2::Tag
*/
namespace ID3v2 {

3
taglib/mpeg/id3v2/id3v2extendedheader.h
View File

@ -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, <a href="id3v2-structure.html#3.2">3.2</a>)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 3.2)
*/
class TAGLIB_EXPORT ExtendedHeader

50
taglib/mpeg/id3v2/id3v2frame.h
View File

@ -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, <a href="id3v2-structure.html#4">4</a>)
* (<a href="id3v2-frames.html">Frames</a>). This class provides an API for
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 4)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>). 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, <a href="id3v2-structure.html#4">4</a>)
* (Frames, <a href="id3v2-frames.html#4">4</a>)
* Returns the Frame ID
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 4)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>, 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, <a href="id3v2-structure.html#4">4</a>)
* The ID3v2 Frame Header
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 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, <a href="id3v2-structure.html#4">4</a>)
* (Frames, <a href="id3v2-frames.html#4">4</a>)
* Returns the Frame ID
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 4)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>, 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;

15
taglib/mpeg/id3v2/id3v2framefactory.h
View File

@ -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 <a href="https://github.com/taglib/taglib/blob/master/tests/test_id3v2framefactory.cpp">
* tests/test_id3v2framefactory.cpp</a> for an example.
*
* This implements both <i>abstract factory</i> and <i>singleton</i> patterns
* of which more information is available on the web and in software design
* textbooks (Notably <i>Design Patterns</i>).
* textbooks (notably <i>Design Patterns</i>).
*
* \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<Frame::Header *, bool> prepareFrameHeader(
ByteVector &data, const Header *tagHeader) const;

11
taglib/mpeg/id3v2/id3v2header.h
View File

@ -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, <a href="id3v2-structure.html#3.1">3.1</a>)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 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;
/*!

5
taglib/mpeg/id3v2/id3v2synchdata.h
View File

@ -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,
* <a href="id3v2-structure.html#6.2">6.2</a>). The default \a length of
* ByteVector that contains a \e synchsafe integer
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 6.2). The default \a length of
* 4 is used if another value is not specified.
*/
TAGLIB_EXPORT unsigned int toUInt(const ByteVector &data);

18
taglib/mpeg/id3v2/id3v2tag.h
View File

@ -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()

36
taglib/mpeg/mpegfile.h
View File

@ -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);

34
taglib/mpeg/mpegheader.h
View File

@ -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
* <a href="http://www.mp3-tech.org/programmer/frame_header.html">this</a>
* document as a reference.
* or less the binary format of these headers.
*
* See these documents as a reference
* - <a href="http://www.mp3-tech.org/programmer/frame_header.html">
* MPEG Audio Layer I/II/III frame header</a>
* - <a href="https://wiki.multimedia.cx/index.php/ADTS">ADTS</a>
*/
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;

8
taglib/mpeg/mpegproperties.h
View File

@ -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;

6
taglib/mpeg/xingheader.h
View File

@ -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 <a href="http://home.pcisys.net/~melanson/codecs/mp3extensions.txt">
* this text</a> and the XMMS sources as references.
* It uses <a href="https://multimedia.cx/mp3extensions.txt">
* mp3extensions.txt</a> 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;

10
taglib/ogg/flac/oggflacfile.h
View File

@ -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 <b>is still</b> owned by the FLAC::File and should not be
* \note The Tag <b>is still</b> 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;

2
taglib/ogg/oggpage.h
View File

@ -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.

10
taglib/ogg/oggpageheader.h
View File

@ -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 <i>continued</i> 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()
*/

6
taglib/ogg/opus/opusfile.h
View File

@ -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;

6
taglib/ogg/speex/speexfile.h
View File

@ -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;

6
taglib/ogg/vorbis/vorbisfile.h
View File

@ -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;

10
taglib/ogg/xiphcomment.h
View File

@ -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<FLAC::Picture *> 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);

6
taglib/riff/aiff/aifffile.h
View File

@ -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

2
taglib/riff/aiff/aiffproperties.h
View File

@ -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;

2
taglib/riff/rifffile.h
View File

@ -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.
*

26
taglib/riff/wav/infotag.h
View File

@ -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<ByteVector, String>;
//! 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<StringHandlerPrivate> 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);

8
taglib/riff/wav/wavfile.h
View File

@ -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.

15
taglib/s3m/s3mfile.h
View File

@ -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:
/*!

1
taglib/s3m/s3mproperties.h
View File

@ -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. */

32
taglib/tag.h
View File

@ -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);

26
taglib/toolkit/taglib.h
View File

@ -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<wchar_t>;
@ -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 <b>Class Hierarchy</b> 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 <b>Class Hierarchy</b> 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}

142
taglib/toolkit/tbytevector.h
View File

@ -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.

2
taglib/toolkit/tbytevectorstream.cpp
View File

@ -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)

16
taglib/toolkit/tbytevectorstream.h
View File

@ -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;

10
taglib/toolkit/tfile.h
View File

@ -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.

18
taglib/toolkit/tfilestream.h
View File

@ -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;

4
taglib/toolkit/tiostream.h
View File

@ -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;

34
taglib/toolkit/tlist.h
View File

@ -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<T> &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<T> &operator=(std::initializer_list<T> 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<T> &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<T> &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<T> &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<class Compare>
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.

30
taglib/toolkit/tmap.h
View File

@ -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<Key, T> &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<Key, T> &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<Key, T> &operator=(std::initializer_list<std::pair<const Key, T>> 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<Key, T> &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<Key, T> &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<Key, T> &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.

27
taglib/toolkit/tpropertymap.h
View File

@ -38,7 +38,7 @@ namespace TagLib {
using SimplePropertyMap = Map<String, StringList>;
//! A map for format-independent <key,valuelist> tag representations.
//! A map for format-independent <key,values> 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;

45
taglib/toolkit/tstring.h
View File

@ -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 <i>implementation detail</i> 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;

4
taglib/toolkit/tstringlist.h
View File

@ -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<String>

59
taglib/toolkit/tvariant.h
View File

@ -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, //!< <tt>unsigned int</tt>
LongLong, //!< <tt>long long</tt>
ULongLong, //!< <tt>unsigned long long</tt>
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<TagLib::Variant> toList(bool *ok = nullptr) const;
//! \copydoc toInt()
TagLib::Map<TagLib::String, TagLib::Variant> 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<typename T>
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;

17
taglib/toolkit/tversionnumber.h
View File

@ -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;

26
taglib/trueaudio/trueaudiofile.h
View File

@ -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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> 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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> owned by the TrueAudio::File and should not be
* deleted by the user. It will be deleted when the file (object) is
* destroyed.
*

24
taglib/wavpack/wavpackfile.h
View File

@ -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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> 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 <b>is still</b> owned by the MPEG::File and should not be
* \note The Tag <b>is still</b> owned by the WavPack::File and should not be
* deleted by the user. It will be deleted when the file (object) is
* destroyed.
*

15
taglib/xm/xmfile.h
View File

@ -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:
/*!

1
taglib/xm/xmproperties.h
View File

@ -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. */