From 30f62ba887ee6b7d2d294ad8d73b006825f626c6 Mon Sep 17 00:00:00 2001 From: Tsuda Kageyu <tsuda.kageyu@gmail.com> Date: Thu, 4 Jul 2013 21:44:28 +0900 Subject: [PATCH] Updated the relevant comments --- taglib/ape/apefile.h | 33 ++++++++++++++++------ taglib/asf/asffile.h | 1 - taglib/flac/flacfile.h | 48 ++++++++++++++++++++++++-------- taglib/mpc/mpcfile.h | 37 ++++++++++++++++-------- taglib/mpeg/mpegfile.h | 46 ++++++++++++++++++++++-------- taglib/ogg/flac/oggflacfile.cpp | 10 +++---- taglib/ogg/flac/oggflacfile.h | 16 +++++++++-- taglib/riff/aiff/aifffile.h | 10 ++++++- taglib/riff/wav/wavfile.h | 20 +++++++++++-- taglib/trueaudio/trueaudiofile.h | 42 ++++++++++++++++++---------- taglib/wavpack/wavpackfile.h | 33 ++++++++++++++++------ 11 files changed, 218 insertions(+), 78 deletions(-) diff --git a/taglib/ape/apefile.h b/taglib/ape/apefile.h index 5530edf3..f7b509f4 100644 --- a/taglib/ape/apefile.h +++ b/taglib/ape/apefile.h @@ -152,27 +152,38 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * an ID3v1 tag if one does not exist and returns a valid pointer. * - * \note The Tag <b>is still</b> owned by the APE::File and should not be + * \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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * a APE tag if one does not exist. + * 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 APE::File and should not be + * \note The Tag <b>is still</b> owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -187,12 +198,16 @@ namespace TagLib { void strip(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const; /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; diff --git a/taglib/asf/asffile.h b/taglib/asf/asffile.h index 4e850d6d..3ce3837a 100644 --- a/taglib/asf/asffile.h +++ b/taglib/asf/asffile.h @@ -114,7 +114,6 @@ namespace TagLib { virtual bool save(); private: - int readBYTE(bool *ok = 0); int readWORD(bool *ok = 0); unsigned int readDWORD(bool *ok = 0); diff --git a/taglib/flac/flacfile.h b/taglib/flac/flacfile.h index e159c505..0963f4af 100644 --- a/taglib/flac/flacfile.h +++ b/taglib/flac/flacfile.h @@ -161,39 +161,57 @@ namespace TagLib { /*! * Returns a pointer to the ID3v2 tag of the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * an ID3v2 tag if one does not exist. + * an ID3v2 tag if one does not exist and returns a valid pointer. * - * \note The Tag <b>is still</b> owned by the FLAC::File and should not be + * \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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag(bool create = false); /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. + * 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 + * an APE tag if one does not exist and returns a valid pointer. * - * \note The Tag <b>is still</b> owned by the FLAC::File and should not be + * \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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the XiphComment for the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * a XiphComment if one does not exist. + * 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 + * 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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasXiphComment() */ Ogg::XiphComment *xiphComment(bool create = false); @@ -247,17 +265,23 @@ namespace TagLib { void addPicture(Picture *picture); /*! - * Returns whether or not the file on disk contains a Xiph comment. + * Returns whether or not the file on disk actually has a XiphComment. + * + * \see xiphComment() */ bool hasXiphComment() const; /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; diff --git a/taglib/mpc/mpcfile.h b/taglib/mpc/mpcfile.h index 4db906b5..1eef8103 100644 --- a/taglib/mpc/mpcfile.h +++ b/taglib/mpc/mpcfile.h @@ -145,28 +145,39 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * 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 + * 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 APE::File and should not be + * \note The Tag <b>is still</b> owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * a APE tag if one does not exist. If there is already an ID3v1 tag, thes - * new APE tag will be placed before it. + * 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. + * + * \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 APE::File and should not be + * \note The Tag <b>is still</b> owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -188,12 +199,16 @@ namespace TagLib { void remove(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const; diff --git a/taglib/mpeg/mpegfile.h b/taglib/mpeg/mpegfile.h index be94be7f..3fc01e68 100644 --- a/taglib/mpeg/mpegfile.h +++ b/taglib/mpeg/mpegfile.h @@ -238,39 +238,57 @@ namespace TagLib { /*! * Returns a pointer to the ID3v2 tag of the file. * - * A tag will always be returned, regardless of whether there is a - * tag in the file or not. Use ID3v2::Tag::isEmpty() to check if - * the tag contains no data. + * 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 + * 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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag(bool create = false); /*! * Returns a pointer to the ID3v1 tag of the file. * - * A tag will always be returned, regardless of whether there is a - * tag in the file or not. Use Tag::isEmpty() to check if - * the tag contains no data. + * 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 + * 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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * an APE tag if one does not exist. + * 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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -327,17 +345,23 @@ namespace TagLib { long lastFrameOffset(); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const; diff --git a/taglib/ogg/flac/oggflacfile.cpp b/taglib/ogg/flac/oggflacfile.cpp index d440a0c6..bdf82459 100644 --- a/taglib/ogg/flac/oggflacfile.cpp +++ b/taglib/ogg/flac/oggflacfile.cpp @@ -137,6 +137,11 @@ bool Ogg::FLAC::File::save() return Ogg::File::save(); } +bool Ogg::FLAC::File::hasXiphComment() const +{ + return d->hasXiphComment; +} + //////////////////////////////////////////////////////////////////////////////// // private members //////////////////////////////////////////////////////////////////////////////// @@ -287,8 +292,3 @@ void Ogg::FLAC::File::scan() d->scanned = true; } - -bool Ogg::FLAC::File::hasXiphComment() const -{ - return d->hasXiphComment; -} diff --git a/taglib/ogg/flac/oggflacfile.h b/taglib/ogg/flac/oggflacfile.h index 77280eff..8d87e486 100644 --- a/taglib/ogg/flac/oggflacfile.h +++ b/taglib/ogg/flac/oggflacfile.h @@ -91,11 +91,19 @@ namespace TagLib { /*! * Returns the Tag for this file. This will always be a XiphComment. + * + * \note This always returns a valid pointer regardless of whether or not + * 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 + * deleted by the user. It will be deleted when the file (object) is + * destroyed. + * + * \see hasXiphComment() */ virtual XiphComment *tag() const; - - /*! * Returns the FLAC::Properties for this file. If no audio properties * were read then this will return a null pointer. @@ -129,7 +137,9 @@ namespace TagLib { long streamLength(); /*! - * Returns whether or not the file on disk contains a Xiph comment. + * Returns whether or not the file on disk actually has a XiphComment. + * + * \see tag() */ bool hasXiphComment() const; diff --git a/taglib/riff/aiff/aifffile.h b/taglib/riff/aiff/aifffile.h index ef72dcd7..c75b94b4 100644 --- a/taglib/riff/aiff/aifffile.h +++ b/taglib/riff/aiff/aifffile.h @@ -85,6 +85,12 @@ namespace TagLib { /*! * Returns the Tag for this file. + * + * \note This always returns 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. + * + * \see hasID3v2Tag() */ virtual ID3v2::Tag *tag() const; @@ -114,7 +120,9 @@ namespace TagLib { virtual bool save(); /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; diff --git a/taglib/riff/wav/wavfile.h b/taglib/riff/wav/wavfile.h index be5e5d15..2f83332a 100644 --- a/taglib/riff/wav/wavfile.h +++ b/taglib/riff/wav/wavfile.h @@ -105,11 +105,23 @@ namespace TagLib { /*! * Returns the ID3v2 Tag for this file. + * + * \note This always returns 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. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag() const; /*! * Returns the RIFF INFO Tag for this file. + * + * \note This always returns a valid pointer regardless of whether or not + * the file on disk has a RIFF INFO tag. Use hasInfoTag() to check if the + * file on disk actually has a RIFF INFO tag. + * + * \see hasInfoTag() */ Info::Tag *InfoTag() const; @@ -141,12 +153,16 @@ namespace TagLib { bool save(TagTypes tags, bool stripOthers = true, int id3v2Version = 4); /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; /*! - * Returns whether or not the file on disk contains an RIFF INFO tag. + * Returns whether or not the file on disk actually has a RIFF INFO tag. + * + * \see InfoTag() */ bool hasInfoTag() const; diff --git a/taglib/trueaudio/trueaudiofile.h b/taglib/trueaudio/trueaudiofile.h index 94c6102b..dbaafcdb 100644 --- a/taglib/trueaudio/trueaudiofile.h +++ b/taglib/trueaudio/trueaudiofile.h @@ -173,30 +173,40 @@ namespace TagLib { virtual bool save(); /*! - * Returns a pointer to the ID3v2 tag of the file. + * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v2 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * 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 + * an ID3v1 tag if one does not exist and returns a valid pointer. * - * \note The Tag <b>is still</b> owned by the TrueAudio::File and should not be + * \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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! - * Returns a pointer to the ID3v1 tag of the file. + * Returns a pointer to the ID3v2 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * 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 + * 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 TrueAudio::File and should not be + * \note The Tag <b>is still</b> owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag(bool create = false); @@ -211,12 +221,16 @@ namespace TagLib { void strip(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; diff --git a/taglib/wavpack/wavpackfile.h b/taglib/wavpack/wavpackfile.h index f84d5d78..198e9619 100644 --- a/taglib/wavpack/wavpackfile.h +++ b/taglib/wavpack/wavpackfile.h @@ -140,27 +140,38 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * an ID3v1 tag if one does not exist and returns a valid pointer. * - * \note The Tag <b>is still</b> owned by the APE::File and should not be + * \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 * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * 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 - * a APE tag if one does not exist. + * 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 APE::File and should not be + * \note The Tag <b>is still</b> owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -175,12 +186,16 @@ namespace TagLib { void strip(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const; -- 2.40.0