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