updated api documentation

git-svn-id: http://svn.code.sf.net/p/qmmp-dev/code/trunk/qmmp@1623 90c681e8-e032-0410-971d-27865f9a5e38

20 files changed, 319 insertions, 61 deletions

diff --git a/src/qmmp/CMakeLists.txt b/src/qmmp/CMakeLists.txt
index f9c6e5fd9..bada92b84 100644
--- a/src/qmmp/CMakeLists.txt
+++ b/src/qmmp/CMakeLists.txt
@@ -93,12 +93,12 @@ SET(libqmmp_MOC_HDRS
 
 SET(libqmmp_DEVEL_HDRS
     visual.h
+    recycler.h
     buffer.h
     decoder.h
     output.h
     fileinfo.h
     outputfactory.h
-    decoderfactory.h
     soundcore.h
     effectfactory.h
     effect.h
@@ -107,7 +107,6 @@ SET(libqmmp_DEVEL_HDRS
     volumecontrol.h
     metadatamodel.h
     tagmodel.h
-    qmmpaudioengine.h
     abstractengine.h
     audioparameters.h
     inputsource.h
diff --git a/src/qmmp/abstractengine.h b/src/qmmp/abstractengine.h
index b8dc453c3..f9fa32179 100644
--- a/src/qmmp/abstractengine.h
+++ b/src/qmmp/abstractengine.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2009 by Ilya Kotov                                      *
+ *   Copyright (C) 2009-2010 by Ilya Kotov                                 *
  *   forkotov02@hotmail.ru                                                 *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -32,15 +32,18 @@ class QIODevice;
 class InputSource;
 
 
-/*!
+/*! @brief The AbstractEngine class provides the base interface class of audio audio engines.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class AbstractEngine : public QThread
 {
  Q_OBJECT
 public:
+    /*!
+     * Object contsructor.
+     * @param parent Parent object.
+     */
     AbstractEngine(QObject *parent = 0);
-
     /*!
      * Prepares decoder for usage.
      * Subclass should reimplement this function.
@@ -78,12 +81,12 @@ public:
     QWaitCondition *cond();
     /*!
      * Sets equalizer settings. Each item of \p bands[] and \p reamp should be \b -20.0..20.0
-     * Subclass with own equalizer should reimplement this function.
+     * Subclass should reimplement this function.
      */
     virtual void setEQ(double bands[10], double preamp) = 0;
     /*!
      * Enables equalizer if \p on is \b true or disables it if \p on is \b false
-     * Subclass with own equalizer should reimplement this function.
+     * Subclass should reimplement this function.
      */
     virtual void setEQEnabled(bool on) = 0;
     /*!
diff --git a/src/qmmp/audioconverter.h b/src/qmmp/audioconverter.h
index 010c84e71..5fdaa1caa 100644
--- a/src/qmmp/audioconverter.h
+++ b/src/qmmp/audioconverter.h
@@ -23,7 +23,7 @@
 
 #include "effect.h"
 
-/*!
+/*! @internal
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class AudioConverter : public Effect
diff --git a/src/qmmp/audioparameters.h b/src/qmmp/audioparameters.h
index 2a99305eb..a8d893a12 100644
--- a/src/qmmp/audioparameters.h
+++ b/src/qmmp/audioparameters.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2009 by Ilya Kotov                                      *
+ *   Copyright (C) 2009-2010 by Ilya Kotov                                 *
  *   forkotov02@hotmail.ru                                                 *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -24,24 +24,58 @@
 #include <QtGlobal>
 #include "qmmp.h"
 
-/*!
+/*! @brief The AudioParameters class keeps information about audio settings.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class AudioParameters
 {
 public:
+    /*!
+     * Contsructor.
+     */
     AudioParameters();
+    /*!
+     * Constructs audio settings with the given parameters.
+     * @param srate Sampling rate.
+     * @param chan Number of channels.
+     * @param format PCM data format.
+     */
     AudioParameters(quint32 srate, int chan, Qmmp::AudioFormat format);
+    /*!
+     * Constructs a copy of \b other.
+     */
     AudioParameters(const AudioParameters &other);
-
+    /*!
+     * Assigns audio parameters \b p to this parameters.
+     */
     void operator=(const AudioParameters &p);
+    /*!
+     * Returns \b true if parameters \b p is equal to this parameters; otherwise returns \b false.
+     */
     bool operator==(const AudioParameters &p) const;
+    /*!
+     * Returns \b true if parameters \b p is not equal to this parameters; otherwise returns \b false.
+     */
     bool operator!=(const AudioParameters &p) const;
-
+    /*!
+     * Returns sample rate in Hz.
+     */
     quint32 sampleRate() const;
+    /*!
+     * Returns number of channels.
+     */
     int channels() const;
+    /*!
+     * Returns pcm format.
+     */
     Qmmp::AudioFormat format() const;
+    /*!
+     * Returns sample size in bytes.
+     */
     int sampleSize() const;
+    /*!
+     * Returns sample size in bytes of the given pcm data \b format.
+     */
     static int sampleSize(Qmmp::AudioFormat format);
 
 private:
diff --git a/src/qmmp/decoder.h b/src/qmmp/decoder.h
index 867c2f830..fad61295b 100644
--- a/src/qmmp/decoder.h
+++ b/src/qmmp/decoder.h
@@ -29,7 +29,8 @@ class Decoder
 {
 public:
     /*!
-     *
+     * Object contsructor.
+     * @param input QIODevice-based input source.
      */
     Decoder(QIODevice *input = 0);
     /*!
@@ -61,12 +62,34 @@ public:
      * Subclass should reimplement this function.
      */
     virtual int bitrate() = 0;
+    /*!
+     * Tells decoder that it should play next track.
+     * By default this function does nothing.
+     * Reimplemet it if your decoder can play next track without stop/start cycle.
+     * This may be useful for multitrack formats like cue or cda.
+     */
     virtual void next();
+    /*!
+     * Returns url which decoder can play without stop/start cycle.
+     * By default this function does nothing.
+     * Reimplemet it if your decoder can play next track without stop/start cycle.
+     */
     virtual const QString nextURL();
-
+    /*!
+     * Returns detected audio parameters.
+     */
     AudioParameters audioParameters() const;
+    /*!
+     * Returns ReplayGain information.
+     */
     QMap<Qmmp::ReplayGainKey, double> replayGainInfo() const;
+    /*!
+     * Sets ReplayGain information. Use this function before playback.
+     */
     void setReplayGainInfo(const QMap<Qmmp::ReplayGainKey,double> &rg);
+    /*!
+     * Returns QIODevice-based input source assigned for this decoder.
+     */
     QIODevice *input();
     /*!
      * Returns DecoderFactory pointer which supports file \b path or 0 if file \b path is unsupported
diff --git a/src/qmmp/effect.h b/src/qmmp/effect.h
index 71cd7b63f..eacee0ca9 100644
--- a/src/qmmp/effect.h
+++ b/src/qmmp/effect.h
@@ -49,7 +49,7 @@ public:
     /*!
      * Prepares object for usage.
      * Subclasses that reimplement this function must call the base implementation.
-     * @param freq Sample rate.
+     * @param srate Sample rate.
      * @param chan Number of channels.
      * @param f Audio format.
      */
@@ -66,10 +66,14 @@ public:
      * Returns audio format.
      */
     Qmmp::AudioFormat format();
-
+    /*!
+     * Returns audio parameters for output data.
+     */
     const AudioParameters audioParameters() const;
+    /*!
+     * Returns assigned factory object.
+     */
     EffectFactory* factory() const;
-
     /*!
      * Creates a list of enabled effects.
      */
diff --git a/src/qmmp/effectfactory.h b/src/qmmp/effectfactory.h
index c5cd35e6c..3ab46d4cd 100644
--- a/src/qmmp/effectfactory.h
+++ b/src/qmmp/effectfactory.h
@@ -27,7 +27,7 @@ class QWidget;
 class QTranslator;
 class Effect;
 
-/*! @brief Helper class to store effect plugin properies.
+/*! @brief Helper class to store effect plugin properties.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class EffectProperties
diff --git a/src/qmmp/emptyinputsource.h b/src/qmmp/emptyinputsource.h
index c2c30db7f..09798791b 100644
--- a/src/qmmp/emptyinputsource.h
+++ b/src/qmmp/emptyinputsource.h
@@ -23,7 +23,7 @@
 
 #include "inputsource.h"
 
-/**
+/*! @internal
     @author Ilya Kotov <forkotov02@hotmail.ru>
 */
 class EmptyInputSource : public InputSource
diff --git a/src/qmmp/fileinputsource.h b/src/qmmp/fileinputsource.h
index 5efe2a2b2..084a412ab 100644
--- a/src/qmmp/fileinputsource.h
+++ b/src/qmmp/fileinputsource.h
@@ -25,7 +25,7 @@
 
 class QFile;
 
-/**
+/** @internal
     @author Ilya Kotov <forkotov02@hotmail.ru>
 */
 class FileInputSource : public InputSource
diff --git a/src/qmmp/inputsource.h b/src/qmmp/inputsource.h
index 06a33b55b..9c708dbab 100644
--- a/src/qmmp/inputsource.h
+++ b/src/qmmp/inputsource.h
@@ -27,21 +27,51 @@
 #include <QIODevice>
 #include "inputsourcefactory.h"
 
-/*!
+/*! @brief The InputSource class provides the base interface class of transports.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class InputSource : public QObject
 {
 Q_OBJECT
 public:
+    /*!
+     * Object contsructor.
+     * @param url Input source path or url.
+     * @param parent Parent object.
+     */
     InputSource(const QString &url, QObject *parent = 0);
+    /*!
+     * Returns QIODevice-based object for I/O operations.
+     * Subclass shoud reimplement this function.
+     */
     virtual QIODevice *ioDevice() = 0;
+    /*!
+     * Prepares input data source for usage.
+     * Subclass shoud reimplement this function.
+     */
     virtual bool initialize() = 0;
+    /*!
+     * Returns \b true if transport is ready for usage; otherwise returns \b false.
+     */
     virtual bool isReady() = 0;
+    /*!
+     * Returns input source path or url.
+     */
     const QString url() const;
+    /*!
+     * Returns start position is ms;
+     */
     qint64 offset() const;
+    /*!
+     * Sets start position to \b offset ms.
+     */
     void setOffset(qint64 offset);
-
+    /*!
+     * Creates InputSource object.
+     * @param url Input source path or url.
+     * @param parent Parent object.
+     * Returns \b 0 if the given url is not supported.
+     */
     static InputSource *create(const QString &url, QObject *parent = 0);
     /*!
      * Returns a list of transport factories.
@@ -53,7 +83,11 @@ public:
     static QStringList files();
 
 signals:
-    void ready(InputSource *);
+    /*!
+     * This signal is emitted when transport is ready for usage.
+     * @param s Pointer of this object.
+     */
+    void ready(InputSource *s);
 
 private:
     QString m_url;
diff --git a/src/qmmp/metadatamanager.h b/src/qmmp/metadatamanager.h
index 8c5e288e7..5e40894be 100644
--- a/src/qmmp/metadatamanager.h
+++ b/src/qmmp/metadatamanager.h
@@ -32,13 +32,20 @@ class DecoderFactory;
 class EngineFactory;
 class InputSourceFactory;
 class QmmpSettings;
-/*!
+
+/*! @brief The MetaDataManager class is the base class for metadata access.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class MetaDataManager
 {
 public:
+    /*!
+     * Constructor. Use MetaDataManager::instance() instead.
+     */
     MetaDataManager();
+    /*!
+     * Destructor. Use MetaDataManager::destroy() instead.
+     */
     ~MetaDataManager();
     /*!
      * Extracts metadata and audio information from file \b path and returns a list of FileInfo items.
@@ -89,7 +96,11 @@ public:
      * Returns a pointer to the MetaDataManager instance.
      */
     static MetaDataManager* instance();
+    /*!
+     * Destroys MetaDataManager object.
+     */
     static void destroy();
+
 private:
     QFileInfoList findCoverFiles(QDir dir, int depth) const;
     QList <DecoderFactory *> *m_decoderFactories;
diff --git a/src/qmmp/metadatamodel.h b/src/qmmp/metadatamodel.h
index d787fe5e1..f95797b8e 100644
--- a/src/qmmp/metadatamodel.h
+++ b/src/qmmp/metadatamodel.h
@@ -28,16 +28,45 @@
 #include <QPixmap>
 #include "tagmodel.h"
 
+/*! @brief The MetaDataModel is the base interface class of metadata access.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class MetaDataModel : public QObject
 {
 Q_OBJECT
 public:
+    /*!
+     * Constructor.
+     * @param parent Parent Object.
+     */
     MetaDataModel(QObject *parent = 0);
+    /*!
+     * Destructor.
+     */
     virtual ~MetaDataModel();
+    /*!
+     * Returns an associative array of the audio properties.
+     * Subclass should reimplement this function. Default implementation returns empty array.
+     */
     virtual QHash<QString, QString> audioProperties();
+    /*!
+     * Returns an associative array of the long descriptions.
+     * Subclass should reimplement this function. Default implementation returns empty array.
+     */
     virtual QHash<QString, QString> descriptions();
+    /*!
+     * Returns a list of available tags.
+     * Subclass should reimplement this function. Default implementation returns empty array.
+     */
     virtual QList<TagModel* > tags();
+    /*!
+     * Returns cover pixmap.
+     * Subclass should reimplement this function. Default implementation returns empty pixmap.
+     */
     virtual QPixmap cover();
+    /*!
+     * Returns path to cover pixmap.
+     */
     virtual QString coverPath();
 };
 
diff --git a/src/qmmp/output.h b/src/qmmp/output.h
index 82e1b343e..f2c729721 100644
--- a/src/qmmp/output.h
+++ b/src/qmmp/output.h
@@ -104,7 +104,9 @@ public:
      * Returns selected audio format.
      */
     Qmmp::AudioFormat format() const;
-
+    /*!
+     * Returns sample size in bytes.
+     */
     int sampleSize() const;
     /*!
      * Creates selected output.
diff --git a/src/qmmp/qmmp.h b/src/qmmp/qmmp.h
index 2f30d0c6d..ebc7d226f 100644
--- a/src/qmmp/qmmp.h
+++ b/src/qmmp/qmmp.h
@@ -56,12 +56,15 @@ public:
         DISCNUMBER,/*!< Disc number */
         URL        /*!< Stream url or local file path */
     };
+    /*!
+     * Keys of ReplayGain information
+     */
     enum ReplayGainKey
     {
-        REPLAYGAIN_TRACK_GAIN = 0,
-        REPLAYGAIN_TRACK_PEAK,
-        REPLAYGAIN_ALBUM_GAIN,
-        REPLAYGAIN_ALBUM_PEAK
+        REPLAYGAIN_TRACK_GAIN = 0, /*!< track gain */
+        REPLAYGAIN_TRACK_PEAK,     /*!< track peak */
+        REPLAYGAIN_ALBUM_GAIN,     /*!< album gain */
+        REPLAYGAIN_ALBUM_PEAK      /*!< album peak */
     };
     /*!
      * Audio formats
diff --git a/src/qmmp/qmmp.pro b/src/qmmp/qmmp.pro
index 316a969c2..018ddd00e 100644
--- a/src/qmmp/qmmp.pro
+++ b/src/qmmp/qmmp.pro
@@ -78,21 +78,29 @@ contains(CONFIG, SVN_VERSION) {
 unix { 
     target.path = $$LIB_DIR
     devel.files += buffer.h \
-        decoderfactory.h \
-        decoder.h \
-        effectfactory.h \
-        effect.h \
-        fileinfo.h \
-        outputfactory.h \
-        output.h \
-        qmmp.h \
-        recycler.h \
-        soundcore.h \
-        statehandler.h \
-        visualfactory.h \
-        visual.h \
-        volumecontrol.h \
-        abstractdetailsdialog.h
+                   buffer.h \
+                   decoder.h \
+                   output.h \
+                   outputfactory.h \
+                   decoderfactory.h \
+                   soundcore.h \
+                   visual.h \
+                   visualfactory.h \
+                   effect.h \
+                   effectfactory.h \
+                   statehandler.h \
+                   qmmp.h \
+                   fileinfo.h \
+                   volumecontrol.h \
+                   metadatamodel.h \
+                   tagmodel.h \
+                   abstractengine.h \
+                   audioparameters.h \
+                   inputsource.h \
+                   inputsourcefactory.h \
+                   enginefactory.h \
+                   metadatamanager.h \
+                   qmmpsettings.h
     devel.path = /include/qmmp
     INSTALLS += target \
         devel
diff --git a/src/qmmp/qmmpaudioengine.h b/src/qmmp/qmmpaudioengine.h
index 47b5cca01..4b57c4149 100644
--- a/src/qmmp/qmmpaudioengine.h
+++ b/src/qmmp/qmmpaudioengine.h
@@ -37,6 +37,9 @@ class EffectFactory;
 class ReplayGain;
 class QmmpSettings;
 
+/*! @internal
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class QmmpAudioEngine : public AbstractEngine
 {
 Q_OBJECT
diff --git a/src/qmmp/qmmpsettings.h b/src/qmmp/qmmpsettings.h
index 35b87d959..0776a33f0 100644
--- a/src/qmmp/qmmpsettings.h
+++ b/src/qmmp/qmmpsettings.h
@@ -25,31 +25,69 @@
 #include <QUrl>
 #include <QStringList>
 
-/*!
+/*! @brief The QmmpSettings class provides access to global settings.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class QmmpSettings : public QObject
 {
 Q_OBJECT
 public:
+    /*!
+     * Constructor.
+     * @param parent Parent object.
+     * This functions is for internal usage only, use QmmpSettings::instance() instead.
+     */
     QmmpSettings(QObject *parent = 0);
+    /*!
+     * Destructor.
+     */
     ~QmmpSettings();
-
+    /*!
+     * This enum describes possible replaygain modes.
+     */
     enum ReplayGainMode
     {
-        REPLAYGAIN_TRACK = 0,
-        REPLAYGAIN_ALBUM,
-        REPLAYGAIN_DISABLED
+        REPLAYGAIN_TRACK = 0, /*!< Use track gain/peak */
+        REPLAYGAIN_ALBUM,     /*!< Use album gain/peak */
+        REPLAYGAIN_DISABLED   /*!< Disable ReplayGain */
     };
-
+    /*!
+     * Returns current ReplayGain mode.
+     */
     QmmpSettings::ReplayGainMode replayGainMode() const;
+    /*!
+     * Returns preamp in dB.
+     */
     double replayGainPreamp() const;
+    /*!
+     * Returns default gain in dB.
+     */
     double replayGainDefaultGain() const;
+    /*!
+     * Returns \b true if clipping prevention is enabled; otherwise returns \b false.
+     */
     bool replayGainPreventClipping() const;
+    /*!
+     * Sets ReplayGains settings.
+     * @param mode ReplayGain mode.
+     * @param preamp Preamp in dB.
+     * @param default_gain Default gain in dB.
+     * @param clip Clipping prevention state.
+     */
     void setReplayGainSettings(ReplayGainMode mode, double preamp, double default_gain, bool clip);
-
+    /*!
+     * Returns \b true if software volume is enabled; otherwise returns \b false.
+     */
     bool useSoftVolume() const;
+    /*!
+     * Returns \b true if 16-bit converter is enabled; otherwise returns \b false.
+     */
     bool use16BitOutput() const;
+    /*!
+     * Sets audio settings.
+     * @param soft_volume State of software volume.
+     * @param use_16bit State of the 16-bit audio converter.
+     */
     void setAudioSettings(bool soft_volume, bool use_16bit);
     /*!
      * If \b include is \b true, this function returns include cover file name filters,
@@ -60,6 +98,9 @@ public:
      * Returns a depth of recursive cover file search.
      */
     int coverSearchDepth() const;
+    /*!
+     * Returns \b true if cover file search is enabled; otherwise returns \b false.
+     */
     bool useCoverFiles() const;
     /*!
      * Sets cover search options.
@@ -67,6 +108,8 @@ public:
      * @param exc Exclude cover name filters
      * @param depth Depth of recursive cover file search.
      * Recursive cover file search can be disabled by setting \b depth to \b 0.
+     * @param use_files Use or not use files with covers.
+     * This parameter doesn't take effect in embedded covers.
      */
     void setCoverSettings(QStringList inc, QStringList exc, int depth, bool use_files);
     /*!
@@ -81,15 +124,34 @@ public:
      * Returns global proxy url.
      */
     QUrl proxy() const;
+    /*!
+     * Sets network settings.
+     * @param use_proxy Enables or disables global proxy.
+     * @param auth Enables or disables proxy authentication.
+     * @param proxy Proxy url.
+     */
     void setNetworkSettings(bool use_proxy, bool auth, const QUrl &proxy);
-
-
+    /*!
+     * Returns a pointer to the QmmpSettings instance.
+     */
     static QmmpSettings* instance();
 
 signals:
+    /*!
+     * Emitted when ReplayGain settings are changed.
+     */
     void replayGainSettingsChanged();
+    /*!
+     * Emitted when audio settings are changed.
+     */
     void audioSettingsChanged();
+    /*!
+     * Emitted when cover settings are changed.
+     */
     void coverSettingsChanged();
+    /*!
+     * Emitted when network settings are changed.
+     */
     void networkSettingsChanged();
 
 private slots:
diff --git a/src/qmmp/replaygain.h b/src/qmmp/replaygain.h
index 56bc0c7a3..50b3a373a 100644
--- a/src/qmmp/replaygain.h
+++ b/src/qmmp/replaygain.h
@@ -26,7 +26,7 @@
 #include "qmmpsettings.h"
 #include "qmmp.h"
 
-/*!
+/*! @internal
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class ReplayGain
diff --git a/src/qmmp/statehandler.h b/src/qmmp/statehandler.h
index 3bcb089f4..cffa9a3ec 100644
--- a/src/qmmp/statehandler.h
+++ b/src/qmmp/statehandler.h
@@ -65,7 +65,7 @@ public:
     virtual void dispatch(Qmmp::State state);
     /*!
      * Sends buffering progress.
-     * @param \b percent Indicates the current percentage of buffering completed.
+     * @param percent Indicates the current percentage of buffering completed.
      */
     virtual void dispatchBuffer(int percent);
     /*!
@@ -144,7 +144,7 @@ signals:
     */
     void finished();
     /*!
-     *
+     * Emitted before the playback ends.
      */
     void aboutToFinish();
      /*!
diff --git a/src/qmmp/tagmodel.h b/src/qmmp/tagmodel.h
index 582db9bad..c3e2fbf18 100644
--- a/src/qmmp/tagmodel.h
+++ b/src/qmmp/tagmodel.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2009 by Ilya Kotov                                      *
+ *   Copyright (C) 2009-2010 by Ilya Kotov                                 *
  *   forkotov02@hotmail.ru                                                 *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -25,26 +25,69 @@
 #include <QList>
 #include "qmmp.h"
 
+/*! @brief The StateHandler class provides is the base interface class of tag editor.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class TagModel
 {
 public:
+    /*!
+     * This enum describes tag editor capabilities
+     */
     enum Caps
     {
-        NoOptions = 0x0,
-        CreateRemove = 0x1,
-        Save = 0x2,
+        NoOptions = 0x0,    /*!< No capabilities */
+        CreateRemove = 0x1, /*!< Can create/remove tag */
+        Save = 0x2,         /*!< Can save changes */
     };
+    /*!
+     * Constructor.
+     * @param f Capabilities.
+     */
     TagModel(int f = TagModel::CreateRemove | TagModel::Save);
-
+    /*!
+     * Returns tag name.
+     * Subclass should reimplement this fucntion.
+     */
     virtual const QString name() = 0;
+    /*!
+     * Returns available keys. Default implementations returns all possible keys.
+     */
     virtual QList<Qmmp::MetaData> keys();
+    /*!
+     * Returns the metdata string associated with the given \b key.
+     * Subclass should reimplement this fucntion.
+     */
     virtual const QString value(Qmmp::MetaData key) = 0;
+    /*!
+     * Changes metadata string associated with the given \b key to \b value.
+     * Subclass should reimplement this fucntion.
+     */
     virtual void setValue(Qmmp::MetaData key, const QString &value) = 0;
+    /*!
+     * Changes metadata string associated with the given \b key to \b value.
+     * Subclass should reimplement this fucntion.
+     */
     virtual void setValue(Qmmp::MetaData key, int value);
+    /*!
+     * Returns \b true if this tag exists; otherwise returns \b false.
+     */
     virtual bool exists();
+    /*!
+     * Creates tag.
+     */
     virtual void create();
+    /*!
+     * Removes tag.
+     */
     virtual void remove();
+    /*!
+     * Saves tag.
+     */
     virtual void save();
+    /*!
+     * Returns capability flags.
+     */
     int caps();
 
 private: