Add warnings about calling File::save() repeatedly.

taglib/ape/apefile.h

@@ -146,6 +146,9 @@ namespace TagLib {
        *
        * \note According to the official Monkey's Audio SDK, an APE file
        * can only have either ID3V1 or APE tags, so a parameter is used here.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       virtual bool save();
 

taglib/asf/asffile.h

@@ -112,6 +112,9 @@ namespace TagLib {
        * Save the file.
        *
        * This returns true if the save was successful.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       virtual bool save();
 

taglib/flac/flacfile.h

@@ -155,6 +155,9 @@ namespace TagLib {
        * has no XiphComment, one will be constructed from the ID3-tags.
        *
        * This returns true if the save was successful.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       virtual bool save();
 

taglib/mp4/mp4file.h

@@ -111,6 +111,9 @@ namespace TagLib {
        * Save the file.
        *
        * This returns true if the save was successful.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       bool save();
 

taglib/mpc/mpcfile.h

@@ -139,6 +139,11 @@ namespace TagLib {
 
       /*!
        * Saves the file.
+       *
+       * This returns true if the save was successful.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       virtual bool save();
 

taglib/mpeg/mpegfile.h

@@ -175,6 +175,9 @@ namespace TagLib {
        * If you would like more granular control over the content of the tags,
        * with the concession of generality, use parameterized save call below.
        *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
+       *
        * \see save(int tags)
        */
       virtual bool save();
@@ -187,6 +190,9 @@ namespace TagLib {
        * This strips all tags not included in the mask, but does not modify them
        * in memory, so later calls to save() which make use of these tags will
        * remain valid.  This also strips empty tags.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       bool save(int tags);
 
@@ -198,6 +204,9 @@ namespace TagLib {
        * If \a stripOthers is true this strips all tags not included in the mask,
        * but does not modify them in memory, so later calls to save() which make
        * use of these tags will remain valid.  This also strips empty tags.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       // BIC: combine with the above method
       bool save(int tags, bool stripOthers);
@@ -213,6 +222,9 @@ namespace TagLib {
        *
        * The \a id3v2Version parameter specifies the version of the saved
        * ID3v2 tag. It can be either 4 or 3.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       // BIC: combine with the above method
       bool save(int tags, bool stripOthers, int id3v2Version);
@@ -231,6 +243,9 @@ namespace TagLib {
        *
        * If \a duplicateTags is true and at least one tag -- ID3v1 or ID3v2 --
        * exists this will duplicate its content into the other tag.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       // BIC: combine with the above method
       bool save(int tags, bool stripOthers, int id3v2Version, bool duplicateTags);

taglib/ogg/flac/oggflacfile.h

@@ -127,6 +127,9 @@ namespace TagLib {
       /*!
        * Save the file.  This will primarily save and update the XiphComment.
        * Returns true if the save is successful.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  It leads to a segfault.
        */
       virtual bool save();
 

taglib/ogg/opus/opusfile.h

@@ -106,6 +106,14 @@ namespace TagLib {
          */
         virtual Properties *audioProperties() const;
 
+        /*!
+         * Save the file.
+         *
+         * This returns true if the save was successful.
+         *
+         * \warning In the current implementation, it's dangerous to call save()
+         * repeatedly.  It leads to a segfault.
+         */
         virtual bool save();
 
       private:

taglib/ogg/speex/speexfile.h

@@ -106,8 +106,14 @@ namespace TagLib {
          */
         virtual Properties *audioProperties() const;
 
-
-
+        /*!
+         * Save the file.
+         *
+         * This returns true if the save was successful.
+         *
+         * \warning In the current implementation, it's dangerous to call save()
+         * repeatedly.  It leads to a segfault.
+         */
         virtual bool save();
 
       private:

taglib/ogg/vorbis/vorbisfile.h

@@ -114,6 +114,14 @@ namespace TagLib {
        */
       virtual Properties *audioProperties() const;
 
+      /*!
+       * Save the file.
+       *
+       * This returns true if the save was successful.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  It leads to a segfault.
+       */
       virtual bool save();
 
     private:

taglib/wavpack/wavpackfile.h

@@ -133,6 +133,11 @@ namespace TagLib {
 
       /*!
        * Saves the file.
+       *
+       * This returns true if the save was successful.
+       *
+       * \warning In the current implementation, it's dangerous to call save()
+       * repeatedly.  At worst it will corrupt the file.
        */
       virtual bool save();