Updated the relevant comments

diff --git a/taglib/ape/apefile.h b/taglib/ape/apefile.h
index 5530edf34f88d80170416743361dedf9b53f23be..f7b509f40c158e6ab5d9deb332ef0f0d44ced32f 100644 (file)
--- 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 4e850d6da8b8e45cd1f81ccf63ddaed136293a88..3ce3837a309c1cc8ddceda8df2cc299f159bd53b 100644 (file)
--- 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 e159c505d80685dd0d7eeb14ac058ad47c793068..0963f4af602759ff3fbdf793dde374429a80987c 100644 (file)
--- 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 4db906b57d7cb8beeb9d32e0374084b4c1e200b6..1eef8103274e777d464201e14fa98fb936084b5a 100644 (file)
--- 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 be94be7f99f7ee45963538685bd86600afb1e8c3..3fc01e680da2e030a27b27dfa41c3d0a1b44ad76 100644 (file)
--- 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 d440a0c6025cf2ca55bd11e92c9803bb7ffb848d..bdf824595c9ef988df3463c8ff04f248e6d0b87a 100644 (file)
--- 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 77280eff6498d4da60a37d54fd174481a171858c..8d87e486b149c72ee7ce5ceb76907a2b7c905eb3 100644 (file)
--- 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 ef72dcd7b168ddc75b534caeffe97b5ed3cd6301..c75b94b4c98626ed7613c4d4e3ae63e5f3e58974 100644 (file)
--- 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 be5e5d15a4a1c0f5bcbc53cdeb8b00db20119a0a..2f83332a2308ab40b3a80676cf266ef265b0f357 100644 (file)
--- 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 94c6102b05bbafaa5164d482ba0c4c8e44ed1eb1..dbaafcdb910d628c8b8c4c5315418242fe048dd3 100644 (file)
--- 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 f84d5d7867a68c25b8b83d168d271480736c2b21..198e9619cfe640b061c33983d88a6c64d65ff4af 100644 (file)
--- 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;