From b05c3161c7cbb1010a7f8c17fda29c4f2cb36b9d Mon Sep 17 00:00:00 2001
From: Michael Helmling <helmling@mathematik.uni-kl.de>
Date: Sat, 25 Feb 2012 19:11:31 +0100
Subject: [PATCH] Added ID3v2 PropertyMap interface documentation.

---
 taglib/mpeg/id3v2/id3v2tag.cpp |  3 +--
 taglib/mpeg/id3v2/id3v2tag.h   | 25 ++++++++++++++++++++++++-
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/taglib/mpeg/id3v2/id3v2tag.cpp b/taglib/mpeg/id3v2/id3v2tag.cpp
index cdfa4353..4731ba55 100644
--- a/taglib/mpeg/id3v2/id3v2tag.cpp
+++ b/taglib/mpeg/id3v2/id3v2tag.cpp
@@ -24,7 +24,6 @@
  ***************************************************************************/
 
 #include <tfile.h>
-#include <tdebug.h>
 
 #include "id3v2tag.h"
 #include "id3v2header.h"
@@ -34,6 +33,7 @@
 #include "tbytevector.h"
 #include "id3v1genres.h"
 #include "tpropertymap.h"
+#include <tdebug.h>
 
 #include "frames/textidentificationframe.h"
 #include "frames/commentsframe.h"
@@ -339,7 +339,6 @@ PropertyMap ID3v2::Tag::properties() const
   PropertyMap properties;
   for(FrameList::ConstIterator it = frameList().begin(); it != frameList().end(); ++it) {
     PropertyMap props = (*it)->asProperties();
-    debug("read properties:\n" + props.toString());
     properties.merge(props);
   }
   return properties;
diff --git a/taglib/mpeg/id3v2/id3v2tag.h b/taglib/mpeg/id3v2/id3v2tag.h
index 56c055a3..3728868a 100644
--- a/taglib/mpeg/id3v2/id3v2tag.h
+++ b/taglib/mpeg/id3v2/id3v2tag.h
@@ -263,7 +263,30 @@ namespace TagLib {
       /*!
        * Implements the unified property interface -- export function.
        * This function does some work to translate the hard-specified ID3v2
-       * frame types into a free-form string-to-stringlist PropertyMap.
+       * frame types into a free-form string-to-stringlist PropertyMap:
+       *  - if ID3v2 frame ID is known by Frame::frameIDToKey(), the returned
+       *    key is used
+       *  - if the frame ID is "TXXX" (user text frame), the description() is
+       *    used as key
+       *  - if the frame ID is "WXXX" (user url frame),
+       *    - if the description is empty or "URL", the key "URL" is used
+       *    - otherwise, the key "URL:<description>" is used;
+       *  - if the frame ID is "COMM" (comments frame),
+       *    - if the description is empty or "COMMENT", the key "COMMENT"
+       *      is used
+       *    - otherwise, the key "COMMENT:<description>" is used;
+       *  - if the frame ID is "USLT" (unsynchronized lyrics),
+       *    - if the description is empty or "LYRICS", the key "LYRICS" is used
+       *    - otherwise, the key "LYRICS:<description>" is used;
+       *  - if the frame ID is "TIPL" (involved peoples list), and if all the
+       *    roles defined in the frame are known in TextIdentificationFrame::involvedPeopleMap(),
+       *    then "<role>=<name>" will be contained in the returned obejct for each
+       *  - if the frame ID is "TMCL" (musician credit list), then
+       *    "PERFORMER:<instrument>=<name>" will be contained in the returned
+       *    PropertyMap for each defined musician
+       *  In any other case, the unsupportedData() of the returned object will contain
+       *  the frame's ID and, in case of a frame ID which is allowed to appear more than
+       *  once, the description, separated by a "/".
        *
        */
       PropertyMap properties() const;