comments++

diff --git a/taglib/mod/modtag.h b/taglib/mod/modtag.h
index 3a21d67caefeb730cf74175f6fe420b0a859e7df..a2041e9c77fbc2f1c3f277255267a9421ba50985 100644 (file)
--- a/taglib/mod/modtag.h
+++ b/taglib/mod/modtag.h
@@ -26,35 +26,123 @@
 
 namespace TagLib {
   namespace Mod {
-    class TAGLIB_EXPORT Tag : public TagLib::Tag {
-      public:
-        Tag();
-        virtual ~Tag();
-
-        String title()   const;
-        String artist()  const;
-        String album()   const;
-        String comment() const;
-        String genre()   const;
-        uint   year()    const;
-        uint   track()   const;
-               String trackerName() const;
-
-        void setTitle  (const String &title);
-        void setArtist (const String &artist);
-        void setAlbum  (const String &album);
-        void setComment(const String &comment);
-        void setGenre  (const String &genre);
-        void setYear (uint year);
-        void setTrack(uint track);
-        void setTrackerName(const String &trackerName);
-
-      private:
-        Tag(const Tag &);
-        Tag &operator=(const Tag &);
-
-        class TagPrivate;
-        TagPrivate *d;
+    /*!
+     * Tags for module files (mod, s3m, it, xm).
+     *
+     * Note that only the \a title is supported as such by most
+     * module file formats.  Except for xm files the \a trackerName
+     * is derived from the file format or the flavour of the file
+     * format.  For xm files it is stored in the file.
+     *
+     * The \a comment tag is not strictly supported by module files,
+     * but it is common practice to abuse instrument/sample/pattern
+     * names as multiline comments.  TagLib does so as well, but
+     * currently does not support writing them.
+     */
+    class TAGLIB_EXPORT Tag : public TagLib::Tag
+    {
+    public:
+      Tag();
+      virtual ~Tag();
+
+      /*!
+       * Returns the track name; if no track name is present in the tag
+       * String::null will be returned.
+       */
+      String title() const;
+
+      /*!
+       * Not supported by module files.  Therefore always returns String::null.
+       */
+      String artist() const;
+
+      /*!
+       * Not supported by module files.  Therefore always returns String::null.
+       */
+      String album() const;
+
+      /*!
+       * Returns the track comment derived from the instrument/sample/pattern
+       * names; if no comment is present in the tag String::null will be
+       * returned.
+       */
+      String comment() const;
+
+      /*!
+       * Not supported by module files.  Therefore always returns String::null.
+       */
+      String genre() const;
+
+      /*!
+       * Not supported by module files.  Therefore always returns 0.
+       */
+      uint year() const;
+
+      /*!
+       * Not supported by module files.  Therefore always returns 0.
+       */
+      uint track() const;
+
+      /*!
+       * Returns the name of the tracker used to create/edit the module file.
+       * Only xm files store this tag to the file as such, for other formats
+       * (mod, s3m, it) this is derived from the file type or the flavour of
+       * the file type.  Therefore only xm file might have an empty
+       * (String::null) tracker name.
+       */
+      String trackerName() const;
+
+      /*!
+       * Sets the title to \a title.  If \a title is String::null then this
+       * value will be cleared.
+       */
+      void setTitle(const String &title);
+
+      /*!
+       * Not supported by module files and therefore ignored.
+       */
+      void setArtist(const String &artist);
+
+      /*!
+       * Not supported by module files and therefore ignored.
+       */
+      void setAlbum(const String &album);
+
+      /*!
+       * Not yet supported.
+       */
+      void setComment(const String &comment);
+
+      /*!
+       * Not supported by module files and therefore ignored.
+       */
+      void setGenre(const String &genre);
+
+      /*!
+       * Not supported by module files and therefore ignored.
+       */
+      void setYear(uint year);
+
+      /*!
+       * Not supported by module files and therefore ignored.
+       */
+      void setTrack(uint track);
+
+      /*!
+       * Sets the tracker name to \a trackerName.  If \a trackerName is
+       * String::null then this value will be cleared.
+       * 
+       * Note that only xm files support this tag.  Setting the
+       * tracker name for other module file formats will be ignored.
+       */
+      void setTrackerName(const String &trackerName);
+
+    private:
+      Tag(const Tag &);
+      Tag &operator=(const Tag &);
+
+      class TagPrivate;
+      TagPrivate *d;
     };
   }
 }