SoundCore class documentation, fixed other documentation

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

28 files changed, 485 insertions, 168 deletions

diff --git a/src/qmmp/buffer.h b/src/qmmp/buffer.h
index 6c9e84f21..13fd42e0e 100644
--- a/src/qmmp/buffer.h
+++ b/src/qmmp/buffer.h
@@ -9,13 +9,15 @@
 
 #include "constants.h"
 
-/*!
+/*! @brief Audio buffer class.
  * @author Brad Hughes <bhughes@trolltech.com>
  */
-
 class Buffer
 {
 public:
+    /*!
+     * Constructs an empty buffer object.
+     */
     Buffer()
     {
         data = new unsigned char[Buffer::size()];
@@ -23,6 +25,9 @@ public:
         rate = 0;
         exceeding = 0;
     }
+    /*!
+     * Destructor.
+     */
     ~Buffer()
     {
         delete data;
@@ -32,11 +37,13 @@ public:
         exceeding = 0;
     }
 
-    unsigned char *data;
-    unsigned long nbytes;
-    unsigned long rate;
-    unsigned long exceeding;
-
+    unsigned char *data;      /*!< Audio data */
+    unsigned long nbytes;     /*!< Audio data size */
+    unsigned long rate;       /*!< Buffer bitrate */
+    unsigned long exceeding;  /*!< The number of bytes on which the size of buffer exceeds the size of the block */
+    /*!
+     * Returns block size.
+     */
     static unsigned long size()
     {
         return globalBlockSize;
diff --git a/src/qmmp/decoder.h b/src/qmmp/decoder.h
index 224ffc33e..8093ad58e 100644
--- a/src/qmmp/decoder.h
+++ b/src/qmmp/decoder.h
@@ -106,7 +106,7 @@ public:
     StateHandler *stateHandler();
     /*!
      * Sets StateHandler pointer. May be used to override default state handler.
-     * @param hanlder StateHandler pointer;
+     * @param handler StateHandler pointer;
      */
     void setStateHandler(StateHandler *handler);
     /*!
@@ -120,7 +120,7 @@ public:
      */
     virtual void setEQEnabled(bool on);
     /*!
-     * Returns \b true if \b file is supported by input plugins, otherwise \b false
+     * Returns \b true if \b file is supported by input plugins, otherwise returns \b false
      */
     static bool supports(const QString &file);
     /*!
@@ -166,11 +166,11 @@ public:
     /*!
      * Sets whether the input plugin is enabled.
      * @param factory Decoder plugin factory.
-     * @param enabled Plugin enable state (\b true - enable, \b false - disable)
+     * @param enable Plugin enable state (\b true - enable, \b false - disable)
      */
     static void setEnabled(DecoderFactory* factory, bool enable = TRUE);
     /*!
-     * Returns \b true if input plugin is enabled, otherwise \b false
+     * Returns \b true if input plugin is enabled, otherwise returns \b false
      * @param factory Decoder plugin factory.
      */
     static bool isEnabled(DecoderFactory* factory);
@@ -193,6 +193,7 @@ protected:
      * Sends audio data to the output plugin.
      * @param data Pointer to audio data.
      * @param size Audio data size.
+     * @param brate Current bitrate (in kbps)
      * @param chan Number of channels.
      */
     qint64 produceSound(char *data, qint64 size, quint32 brate, int chan);
diff --git a/src/qmmp/decoderfactory.h b/src/qmmp/decoderfactory.h
index cd7345e32..f96057e97 100644
--- a/src/qmmp/decoderfactory.h
+++ b/src/qmmp/decoderfactory.h
@@ -54,10 +54,10 @@ public:
     QString description; /*!< File filter description */
     QString contentType; /*!< Supported content types */
     QString protocols;   /*!< Supported protocols. Should be empty if plugin uses stream input. */
-    bool hasAbout;       /*!< Should be \b true if plugin has about dialog, otherwise \b false */
-    bool hasSettings;    /*!< Should be \b true if plugin has settings dialog, otherwise \b false */
-    bool noInput;        /*!< Should be \b true if plugin has own input, otherwise \b false */
-    bool noOutput;       /*!< Should be \b true if plugin has own output, otherwise \b false */
+    bool hasAbout;       /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */
+    bool hasSettings;    /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */
+    bool noInput;        /*!< Should be \b true if plugin has own input, otherwise returns \b false */
+    bool noOutput;       /*!< Should be \b true if plugin has own output, otherwise returns \b false */
 };
 /*! @brief Input plugin interface (decoder factory).
  * @author Ilya Kotov <forkotov02@hotmail.ru>
@@ -70,11 +70,11 @@ public:
     */
     virtual ~DecoderFactory() {}
     /*!
-     * Returns \b true if plugin supports \b source, otherwise \b false
+     * Returns \b true if plugin supports \b source, otherwise returns \b false
      */
     virtual bool supports(const QString &source) const = 0;
     /*!
-     * Returns \b true if plugin can decode data provided by \b d, otherwise \b false
+     * Returns \b true if plugin can decode data provided by \b d, otherwise returns \b false
      */
     virtual bool canDecode(QIODevice *d) const = 0;
     /*!
diff --git a/src/qmmp/effect.h b/src/qmmp/effect.h
index 7d0e325b1..2ed82269c 100644
--- a/src/qmmp/effect.h
+++ b/src/qmmp/effect.h
@@ -85,11 +85,11 @@ public:
     /*!
      * Sets whether the effect plugin is enabled.
      * @param factory Effect plugin factory.
-     * @param enabled Plugin enable state (\b true - enable, \b false - disable)
+     * @param enable Plugin enable state (\b true - enable, \b false - disable)
      */
     static void setEnabled(EffectFactory* factory, bool enable = TRUE);
     /*!
-     * Returns \b true if input plugin is enabled, otherwise \b false
+     * Returns \b true if input plugin is enabled, otherwise returns \b false
      * @param factory Effect plugin factory.
      */
     static bool isEnabled(EffectFactory* factory);
diff --git a/src/qmmp/effectfactory.h b/src/qmmp/effectfactory.h
index 8ca8f2af2..b22580e59 100644
--- a/src/qmmp/effectfactory.h
+++ b/src/qmmp/effectfactory.h
@@ -43,10 +43,10 @@ public:
     }
     QString name;      /*!< Effect plugin full name */
     QString shortName; /*!< Effect plugin short name for internal usage */
-    bool hasAbout;     /*!< Should be \b true if plugin has about dialog, otherwise \b false */
-    bool hasSettings;  /*!< Should be \b true if plugin has settings dialog, otherwise \b false */
+    bool hasAbout;     /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */
+    bool hasSettings;  /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */
 };
-/*! @brief Effect plugin interface (effect factory).
+/*! @brief %Effect plugin interface (effect factory).
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class EffectFactory
diff --git a/src/qmmp/fileinfo.h b/src/qmmp/fileinfo.h
index 418d78795..e2e04e57e 100644
--- a/src/qmmp/fileinfo.h
+++ b/src/qmmp/fileinfo.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2008 by Ilya Kotov                                      *
+ *   Copyright (C) 2008-2009 by Ilya Kotov                                 *
  *   forkotov02@hotmail.ru                                                 *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -26,31 +26,75 @@
 
 #include "qmmp.h"
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The FileInfo class stores metadata and audio information about media file or stream.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class FileInfo
 {
 public:
+    /*!
+     * Constructs a new empty FileInfo that with file \b path
+     */
     FileInfo(const QString &path = QString());
-    FileInfo(const FileInfo &other);
-
+    /*!
+     * Constructs a new FileInfo that is a copy of the given \b info
+     */
+    FileInfo(const FileInfo &info);
+    /*!
+     * Destructor.
+     */
     ~FileInfo();
-
+    /*!
+     * Makes a copy of the given \b info
+     */
     void operator=(const FileInfo &info);
+    /*!
+     * Returns \b true if this FileInfo object refers to \b info; otherwise returns \b false.
+     */
     bool operator==(const FileInfo &info);
+    /*!
+     * Returns \b false if this FileInfo object refers to \b info; otherwise returns \b true.
+     */
     bool operator!=(const FileInfo &info);
-
+    /*!
+     * Returnds file duration in seconds.
+     */
     qint64 length () const;
+    /*!
+     * Returns the metdata string associated with the given \b key.
+     */
     const QString metaData (Qmmp::MetaData key) const;
+    /*!
+     * Returns all meta data in map.
+     */
     const QMap<Qmmp::MetaData, QString>  metaData () const;
+    /*!
+     * Returns \b true if stream/file has no metadata, otherwise returns \b false
+     */
     bool isEmpty() const;
+    /*!
+     * Returns file path or stream url.
+     */
     const QString path() const;
-
+    /*!
+     * Sets file duration to \b length in seconds.
+     */
     void setLength(qint64 length);
+    /*!
+     * Sets metadata \b key to \b value
+     */
     void setMetaData(Qmmp::MetaData key, const QString &value);
+    /*!
+     * Sets metadata \b key to \b value (integer is converted to string)
+     */
     void setMetaData(Qmmp::MetaData key, int value);
+    /*!
+     * Changes all metadata to \b metaData
+     */
     void setMetaData(const QMap <Qmmp::MetaData,  QString> &metaData);
+    /*!
+     * Sets file path or stream url to \b path
+     */
     void setPath(const QString &path);
 
 private:
diff --git a/src/qmmp/output.h b/src/qmmp/output.h
index 7dab61180..f217eadb1 100644
--- a/src/qmmp/output.h
+++ b/src/qmmp/output.h
@@ -84,7 +84,7 @@ public:
     QMutex *mutex();
     /*!
      * Sets StateHandler pointer. May be used to override default state handler.
-     * @param hanlder StateHandler pointer;
+     * @param handler StateHandler pointer;
      */
     void setStateHandler(StateHandler *handler);
     /*!
diff --git a/src/qmmp/outputfactory.h b/src/qmmp/outputfactory.h
index f05332e64..3871552d1 100644
--- a/src/qmmp/outputfactory.h
+++ b/src/qmmp/outputfactory.h
@@ -46,10 +46,10 @@ public:
     }
     QString name;      /*!< Effect plugin full name */
     QString shortName; /*!< Effect plugin short name for internal usage */
-    bool hasAbout;     /*!< Should be \b true if plugin has about dialog, otherwise \b false */
-    bool hasSettings;  /*!< Should be \b true if plugin has settings dialog, otherwise \b false */
+    bool hasAbout;     /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */
+    bool hasSettings;  /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */
 };
-/*! @brief Output plugin interface (output factory).
+/*! @brief %Output plugin interface (output factory).
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class OutputFactory
@@ -73,7 +73,7 @@ public:
      * Returns \b 0 if volume control is not supported by plugin.
      * @param parent Parent object.
      */
-    virtual VolumeControl *createVolumeControl(QObject *) = 0;
+    virtual VolumeControl *createVolumeControl(QObject *parent) = 0;
     /*!
      * Shows settings dialog.
      * @param parent Parent widget.
diff --git a/src/qmmp/qmmp.h b/src/qmmp/qmmp.h
index bb5ae6830..54fe2984a 100644
--- a/src/qmmp/qmmp.h
+++ b/src/qmmp/qmmp.h
@@ -22,23 +22,75 @@
 
 #include <QUrl>
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The Qmmp class stores global settings and enums.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class Qmmp
 {
 public:
-    enum State {Playing = 0, Paused, Stopped, Buffering, NormalError, FatalError};
-    enum MetaData {TITLE = 0, ARTIST, ALBUM, COMMENT, GENRE, YEAR, TRACK, URL};
+    /*!
+     * Playback state enum
+     */
+    enum State
+    {
+        Playing = 0, /*!< The player is playing source */
+        Paused,      /*!< The player has currently paused its playback */
+        Stopped,     /*!< The player is ready to play source */
+        Buffering,   /*!< The Player is waiting for data to be able to start playing.   */
+        NormalError, /*!< Input source is invalid or unsupported. Player should skip this file */
+        FatalError   /*!< This means unrecorvable error die audio output problems. Player should abort playback. */
+    };
+    /*!
+     * Metadata keys
+     */
+    enum MetaData
+    {
+        TITLE = 0, /*!< Title */
+        ARTIST,    /*!< Artist  */
+        ALBUM,     /*!< Album */
+        COMMENT,   /*!< Comment */
+        GENRE,     /*!< Genre */
+        YEAR,      /*!< Year */
+        TRACK,     /*!< Track number */
+        URL        /*!< Stream url or local file path */
+    };
+    /*!
+     * Returns configuration file path.
+     */
     static QString configFile();
+    /*!
+     * Overrides default configuration file path.
+     */
     static void setConfigFile(const QString &path);
+    /*!
+     * Returns %Qmmp library version.
+     */
     static QString strVersion();
-    //global proxy
+    /*!
+     * Returns \b true if global proxy is enabled, otherwise returns \b false
+     */
     static bool useProxy();
+    /*!
+     * Returns \b true if global proxy authentication is enabled, otherwise returns \b false
+     */
     static bool useProxyAuth();
+    /*!
+     * Returns global proxy url.
+     */
     static QUrl proxy();
+    /*!
+     * Enables or disables global proxy.
+     * @param yes Proxy enable state (\b true - enabled, \b false - disabled)
+     */
     static void setProxyEnabled(bool yes);
+    /*!
+     * Enables or disables global proxy authentication.
+     * @param yes Proxy authentication enable state (\b true - enabled, \b false - disabled)
+     */
     static void setProxyAuthEnabled(bool yes);
+    /*!
+     * Sets global proxy url to \b proxy
+     */
     static void setProxy (const QUrl &proxy);
 
 private:
diff --git a/src/qmmp/recycler.h b/src/qmmp/recycler.h
index d73e08702..66ab6e147 100644
--- a/src/qmmp/recycler.h
+++ b/src/qmmp/recycler.h
@@ -12,34 +12,76 @@
 
 class Buffer;
 
-/*!
+/*! @brief The Recycler class provides a queue of audio buffers.
  *  @author Brad Hughes <bhughes@trolltech.com>
  */
 class Recycler
 {
 public:
-    Recycler(unsigned int sz); // sz = size in bytes
+    /*!
+     * Constructor.
+     * @param sz Preferd total size of the all buffers in bytes.
+     */
+    Recycler(unsigned int sz);
+    /*!
+     * Destructor.
+     */
     ~Recycler();
-
+    /*!
+     * Returns \b true if queue if full, otherwise returns \b false
+     */
     bool full() const;
+    /*!
+     * Returns \b true if queue if empty, otherwise returns \b false
+     */
     bool empty() const;
-
+    /*!
+     * Returns a number of available buffers.
+     */
     int available() const;
+    /*!
+     * Returns a number of used buffers.
+     */
     int used() const;
-
-    Buffer *next(); // get next in queue
+    /*!
+     *  Returns next buffer in queue.
+     */
+    Buffer *next();
+    /*!
+     * Returns current buffer for writing.
+     * @param size Buffer size.
+     */
     Buffer *get(unsigned long size); // get next in recycle
-
+    /*!
+     * Adds current buffer to queue.
+     */
     void add(); // add to queue
+    /*!
+     * Removes current buffer from queue.
+     */
     void done(); // add to recycle
-
+    /*!
+     * Clears queue.
+     */
     void clear(); // clear queue
-
+    /*!
+     * Returns size of all buffers in bytes.
+     */
     unsigned int size() const; // size in bytes
-
-    QMutex *mutex() { return &mtx; }
-    QWaitCondition *cond() { return &cnd; }
-
+    /*!
+    * Returns mutex pointer.
+    */
+    QMutex *mutex()
+    {
+        return &mtx;
+    }
+    /*!
+     * Returns wait condition pointer.
+     */
+    QWaitCondition *cond()
+    {
+        return &cnd;
+    }
 
 private:
     unsigned int buffer_count, add_index, done_index, current_count;
diff --git a/src/qmmp/soundcore.h b/src/qmmp/soundcore.h
index c34d9cb3a..3023b7ca9 100644
--- a/src/qmmp/soundcore.h
+++ b/src/qmmp/soundcore.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2006-2008 by Ilya Kotov                                 *
+ *   Copyright (C) 2006-2009 by Ilya Kotov                                 *
  *   forkotov02@hotmail.ru                                                 *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -20,10 +20,8 @@
 #ifndef SOUNDCORE_H
 #define SOUNDCORE_H
 
-
 #include <QObject>
 #include <QString>
-
 #include "decoder.h"
 #include "output.h"
 #include "visual.h"
@@ -32,54 +30,79 @@
 class QIODevice;
 class VolumeControl;
 
-/*!
- *  @author Ilya Kotov <forkotov02@hotmail.ru>
+/*! \brief The SoundCore class provides a simple interface for audio playback.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class SoundCore : public QObject
 {
     Q_OBJECT
 public:
+    /*!
+     * Object constructor.
+     * @param parent Parent object.
+     */
     SoundCore(QObject *parent = 0);
-
+    /*!
+     * Destructor.
+     */
     ~SoundCore();
-
     /*!
-     * Returns length in seconds
+     * Returns length in milliseconds
      */
     qint64 totalTime() const;
-
     /*!
      * Sets equalizer settings. Each item of \p bands[] and \p reamp should be
      *  \b -20.0..20.0
      */
     void setEQ(double bands[10], double preamp);
-
     /*!
-     * Enables equalizer if \p on is \b TRUE or disables it if \p on is \b FALSE
+     * Enables equalizer if \p on is \b true or disables it if \p on is \b false
      */
     void setEQEnabled(bool on);
-
+    /*!
+     * Returns left volume level.
+     */
     int leftVolume();
+    /*!
+     * Returns left volume level.
+     */
     int rightVolume();
+    /*!
+     * Returns \b true if software volume is used, otherwise returns \b false
+     */
     bool softwareVolume();
-
+    /*!
+     * Returns the current time (in milliseconds).
+     */
     qint64 elapsed();
+    /*!
+     * Returns current bitrate (in kbps)
+     */
     int bitrate();
+    /*!
+     * Returns current sample rate (in Hz).
+     */
     int frequency();
+    /*!
+     * Returns sample size (in bits).
+     */
     int precision();
+    /*!
+     * Returns channels number.
+     */
     int channels();
-
     /*!
      * Returns the current state.
-     *
-     * \return the state of the object.
      */
     Qmmp::State state() const;
-
+    /*!
+     * Returns all meta data in map.
+     */
     QMap <Qmmp::MetaData, QString> metaData();
-
+    /*!
+     * Returns the metdata string associated with the given \b key.
+     */
     QString metaData(Qmmp::MetaData key);
-
     /*!
      * Returns a pointer to the SoundCore instance.
      */
@@ -87,61 +110,88 @@ public:
 
 
 public slots:
-
-    void setSoftwareVolume(bool);
-
+    /*!
+     * This funtion allows to force software volume for all output plugins.
+     * @param yes Software volume enable state (\b true - enable, \b false - disable)
+     */
+    void setSoftwareVolume(bool yes);
     /*!
      * Sets volume.
-     * \p left - volume of the left channel.
-     * \p right - volume of the right channel.
-     * \b left and \b right should be \b 0..100.
+     * @param left - volume of the left channel \b [0..100].
+     * @param right - volume of the right channel \b [0..100].
      */
     void setVolume(int left, int right);
-
     /*!
-     *  This function plays file with the given path \p source.
-     *
-     *  \return \b TRUE if playback started successful or source is not a local file.
-     *  \return \b FALSE otherwise.
+     * This function plays file or stream with the given path \p source.
+     * Returns \b true if playback started successful or source is not a local file,
+     * otherwise returns \b false. Useful for invalid files skipping.
      */
     bool play(const QString &source);
-
     /*!
      *  Stops playback
      */
     void stop();
-
     /*!
      *  Pauses/resumes playback
      */
     void pause();
-
     /*!
-    *  This function sets the current play position to \p pos.
-    */
+     *  This function sets the current play position to \p pos in milliseconds.
+     */
     void seek(qint64 pos);
-
     /*!
-    *  This function returns file path or stream url.
-    */
+     *  This function returns file path or stream url.
+     */
     const QString url();
 
 signals:
-
     /*!
-     * This signal is emited when the stream reader fills it's buffer.
-     * The argument \b progress indicates the current percentage of buffering completed
+     * This signal is emitted when the stream reader fills it's buffer.
+     * The argument \b progress indicates the current percentage of buffering completed.
      */
-
     void bufferingProgress(int progress);
+    /*!
+     * Tracks elapesed time.
+     * @param time New track position in milliseconds.
+     */
     void elapsedChanged(qint64 time);
+    /*!
+     * Emitted when bitrate has changed.
+     * @param bitrate New bitrate (in kbps)
+     */
     void bitrateChanged(int bitrate);
+    /*!
+     * Emitted when samplerate has changed.
+     * @param frequency New sample rate (in Hz)
+     */
     void frequencyChanged(int frequency);
+    /*!
+     * Emitted when sample size has changed.
+     * @param precision New sample size (in bits)
+     */
     void precisionChanged(int precision);
+    /*!
+     * Emitted when channels number has changed.
+     * @param channels New channels number.
+     */
     void channelsChanged(int channels);
+    /*!
+     * Emitted when new metadata is available.
+     */
     void metaDataChanged ();
+    /*!
+     * This signal is emitted when the state of the SoundCore has changed.
+     */
     void stateChanged (Qmmp::State newState);
+    /*!
+     * Emitted when playback has finished.
+     */
     void finished();
+    /*!
+     * Emitted when volume has changed.
+     * @param left Left channel volume level. It should be \b [0..100]
+     * @param right Right channel volume level. It should be \b [0..100]
+     */
     void volumeChanged(int left, int right);
 
 private slots:
diff --git a/src/qmmp/statehandler.h b/src/qmmp/statehandler.h
index 702a24c1b..af44c2597 100644
--- a/src/qmmp/statehandler.h
+++ b/src/qmmp/statehandler.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2008 by Ilya Kotov                                      *
+ *   Copyright (C) 2008-2009 by Ilya Kotov                                 *
  *   forkotov02@hotmail.ru                                                 *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -26,50 +26,119 @@
 
 #include "qmmp.h"
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The StateHandler class allows to track information about playback progress.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class StateHandler : public QObject
 {
     Q_OBJECT
 public:
+    /*!
+     * Object constructor.
+     * @param parent Parent object.
+     */
     StateHandler(QObject *parent = 0);
-
+    /*!
+     * Destructor.
+     */
     ~StateHandler();
-
+    /*!
+     * Sends information about playback progress.
+     * @param elapsed Current time (in milliseconds).
+     * @param totalTime Total track length (in milliseconds).
+     * @param bitrate Current bitrate (in kbps).
+     * @param frequency Current samplerate (in Hz).
+     * @param precision Sample size (in bits).
+     * @param channels Number of channels.
+     */
     virtual void dispatch(qint64 elapsed,
                           qint64 totalTime,
                           int bitrate,
                           int frequency,
                           int precision,
                           int channels);
-
+    /*!
+     * Sends metadata \b metaData
+     */
     virtual void dispatch(const QMap<Qmmp::MetaData, QString> &metaData);
-
+    /*!
+     * Sends playback state.
+     */
     virtual void dispatch(const Qmmp::State &state);
-
+    /*!
+     * Returns the current time (in milliseconds).
+     */
     qint64 elapsed();
+    /*!
+     * Returns current bitrate (in kbps)
+     */
     int bitrate();
+    /*!
+     * Returns current sample rate (in Hz).
+     */
     int frequency();
+    /*!
+     * Returns sample size (in bits).
+     */
     int precision();
+    /*!
+     * Returns channels number.
+     */
     int channels();
-    Qmmp::State state();
+    /*!
+     * Returns the current state.
+     */
+    Qmmp::State state() const;
+    /*!
+     * Returns all meta data in map.
+     */
     QMap <Qmmp::MetaData, QString> metaData();
+    /*!
+     * Returns the metdata string associated with the given \b key.
+     */
     QString metaData(Qmmp::MetaData key);
-
     /*!
-     * Returns a pointer to the StateHandler instance.
+     * Returns a pointer to the first created StateHandler instance.
      */
     static StateHandler* instance();
 
 signals:
+    /*!
+     * Tracks elapesed time.
+     * @param time New track position in milliseconds.
+     */
     void elapsedChanged(qint64 time);
+    /*!
+     * Emitted when bitrate has changed.
+     * @param bitrate New bitrate (in kbps)
+     */
     void bitrateChanged(int bitrate);
+    /*!
+     * Emitted when samplerate has changed.
+     * @param frequency New sample rate (in Hz)
+     */
     void frequencyChanged(int frequency);
+    /*!
+     * Emitted when sample size has changed.
+     * @param precision New sample size (in bits)
+     */
     void precisionChanged(int precision);
+    /*!
+     * Emitted when channels number has changed.
+     * @param channels New channels number.
+     */
     void channelsChanged(int channels);
+    /*!
+     * Emitted when new metadata is available.
+     */
     void metaDataChanged ();
+    /*!
+     * This signal is emitted when the playback state has changed.
+     */
     void stateChanged (Qmmp::State newState);
+    /*!
+    * Emitted when playback has finished.
+    */
     void finished();
 
 private:
diff --git a/src/qmmp/visual.h b/src/qmmp/visual.h
index f1b510899..7f3739384 100644
--- a/src/qmmp/visual.h
+++ b/src/qmmp/visual.h
@@ -75,11 +75,11 @@ public:
     /*!
      * Sets whether the visual plugin is enabled.
      * @param factory Visual plugin factory.
-     * @param enabled Plugin enable state (\b true - enable, \b false - disable)
+     * @param enable Plugin enable state (\b true - enable, \b false - disable)
      */
     static void setEnabled(VisualFactory* factory, bool enable = TRUE);
     /*!
-     * Returns \b true if visual plugin is enabled, otherwise \b false
+     * Returns \b true if visual plugin is enabled, otherwise returns \b false
      * @param factory Effect plugin factory.
      */
     static bool isEnabled(VisualFactory* factory);
@@ -111,7 +111,7 @@ public:
 
 signals:
     /*!
-     * Emited when visual widget is closed by user.
+     * Emitted when visual widget is closed by user.
      */
     void closedByUser();
 
diff --git a/src/qmmp/visualfactory.h b/src/qmmp/visualfactory.h
index 1f631392f..fdb3a1abf 100644
--- a/src/qmmp/visualfactory.h
+++ b/src/qmmp/visualfactory.h
@@ -43,10 +43,10 @@ public:
     }
     QString name;      /*!< Effect plugin full name */
     QString shortName; /*!< Effect plugin short name for internal usage */
-    bool hasAbout;     /*!< Should be \b true if plugin has about dialog, otherwise \b false */
-    bool hasSettings;  /*!< Should be \b true if plugin has settings dialog, otherwise \b false */
+    bool hasAbout;     /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */
+    bool hasSettings;  /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */
 };
-/*! Visual plugin interface (visual factory).
+/*! @brief %Visual plugin interface (visual factory).
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class VisualFactory
diff --git a/src/qmmp/volumecontrol.h b/src/qmmp/volumecontrol.h
index 5be1d253f..f993057b7 100644
--- a/src/qmmp/volumecontrol.h
+++ b/src/qmmp/volumecontrol.h
@@ -22,60 +22,113 @@
 
 #include <QObject>
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The VolumeControl class provides the base interface class for volume control.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class VolumeControl : public QObject
 {
     Q_OBJECT
 public:
+    /*!
+     * Object constructor.
+     * @param parent Parent object.
+     */
     VolumeControl(QObject *parent = 0);
-
+    /*!
+     * Destructor.
+     */
     ~VolumeControl();
-
+    /*!
+     * Setups volume level.
+     * Subclass should reimplement this fucntion.
+     * @param left Left channel volume level. It should be \b 0..100
+     * @param right Right channel volume level. It should be \b 0..100
+     */
     virtual void setVolume(int left, int right) = 0;
-
+    /*!
+     * Returns left channel volume.
+     */
     int left();
+    /*!
+     * Returns right channel volume.
+     */
     int right();
-
+    /*!
+     * Creates output volume control object if implemented, \b otherwise it creates SoftwareVolume object.
+     * @param parent Parent object.
+     */
     static VolumeControl *create(QObject *parent = 0);
 
 signals:
+    /*!
+     * Emitted when volume is changed.
+     * @param left Left channel volume level. It should be \b 0..100
+     * @param right Right channel volume level. It should be \b 0..100
+     */
     void volumeChanged(int left, int right);
 
 public slots:
+    /*!
+     * Forces the volumeChanged signal to emit.
+     */
     void checkVolume();
 
 protected:
+    /*!
+     * Gets current volume.
+     * @param left Pointer to the left volume level.
+     * @param right Pointer to the right volume level
+     */
     virtual void volume(int *left, int *right) = 0;
 
 private:
     int m_left, m_right;
 
 };
-/*! @internal
- *  @author Ilya Kotov <forkotov02@hotmail.ru>
+/*! @brief The SoftwareVolume provides access to the software volume control.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class SoftwareVolume : public VolumeControl
 {
     Q_OBJECT
 public:
+    /*!
+     * Object constructor.
+     * @param parent Parent object.
+     */
     SoftwareVolume(QObject *parent = 0);
-
+    /*!
+     * Destructor.
+     */
     ~SoftwareVolume();
-
+    /*!
+     * Setups volume level.
+     * Subclass should reimplement this fucntion.
+     * @param left Left channel volume level. It should be \b 0..100
+     * @param right Right channel volume level. It should be \b 0..100
+     */
     void setVolume(int left, int right);
-
+    /*!
+     * Returns software volume object instance.
+     */
     static SoftwareVolume *instance();
+    /*!
+     * This funtion allows to force software volume for all output plugins.
+     * @param b Software volume enable state (\b true - enable, \b false - disable)
+     */
     static void setEnabled(bool b);
 
 protected:
+    /*! @internal
+     * Gets current volume.
+     * @param left Pointer to the left volume level.
+     * @param right Pointer to the right volume level
+     */
     void volume(int *left, int *right);
 
 private:
     int m_left, m_right;
     static SoftwareVolume *m_instance;
-
 };
 
 #endif
diff --git a/src/qmmpui/abstractplaylistitem.h b/src/qmmpui/abstractplaylistitem.h
index cf594e6e3..2294ff73a 100644
--- a/src/qmmpui/abstractplaylistitem.h
+++ b/src/qmmpui/abstractplaylistitem.h
@@ -90,7 +90,7 @@ public:
     /*!
      * Loads one metadata value.
      * @param key Metadata key.
-     * @param key Metadata vlaue.
+     * @param value Metadata value.
      */
     virtual void setMetaData(Qmmp::MetaData key, const QString &value);
     /*!
diff --git a/src/qmmpui/commandlinemanager.h b/src/qmmpui/commandlinemanager.h
index 8f0660fb6..6bae654ee 100644
--- a/src/qmmpui/commandlinemanager.h
+++ b/src/qmmpui/commandlinemanager.h
@@ -46,7 +46,7 @@ public:
      */
     void executeCommand(const QString& opt_str);
     /*!
-     * Return \b true if command \b opt_str is supported, otherwise \b false
+     * Return \b true if command \b opt_str is supported, otherwise returns \b false
      */
     static bool hasOption(const QString &opt_str);
     /*!
diff --git a/src/qmmpui/filedialog.h b/src/qmmpui/filedialog.h
index c5ccff59b..7395ffea0 100644
--- a/src/qmmpui/filedialog.h
+++ b/src/qmmpui/filedialog.h
@@ -115,7 +115,6 @@ public:
      * @param caption Dialog title.
      * @param filters Filer used by file dialog
      * (example: "Audio (*.mp3 *.ogg);;Text files (*.txt);;XML files (*.xml)").
-     * @param selectedFilter Default selected filter.
      *
      * Usage: FileDialog::popup(this, FileDialog::AddDirs, &m_lastDir,
      *                 m_playListModel, SLOT(addFileList(const QStringList&)),
@@ -133,7 +132,7 @@ public:
      */
     static QList <FileDialogFactory*> registeredFactories();
     /*!
-     * Returns \b true if selected file dialog doesn't support nonmodal mode, otherwise \b false
+     * Returns \b true if selected file dialog doesn't support nonmodal mode, otherwise returns \b false
      */
     static bool isModal();
     /*!
@@ -141,7 +140,7 @@ public:
      */
     static void setEnabled(FileDialogFactory *factory);
     /*!
-     * Returns \b true if file dialog \b factory is used by default, otherwise \b false
+     * Returns \b true if file dialog \b factory is used by default, otherwise returns \b false
      */
     static bool isEnabled(FileDialogFactory *factory);
 
@@ -215,7 +214,7 @@ protected:
                                    const QString &filter ,
                                    QString *selectedFilter);
     /*!
-     * Returns \b true if file dialog doesn't support nonmodal mode, otherwise \b false
+     * Returns \b true if file dialog doesn't support nonmodal mode, otherwise returns \b false
      * Subclass should reimplement this function.
      */
     virtual bool modal()const
@@ -258,7 +257,7 @@ protected:
     static FileDialog* defaultInstance();
     /*!
      * Registers file dialog \b factory
-     * Returns \b false if \b factory is already registered, otherwise \b true
+     * Returns \b false if \b factory is already registered, otherwise returns \b true
      */
     static bool registerFactory(FileDialogFactory *factory);
 
diff --git a/src/qmmpui/filedialogfactory.h b/src/qmmpui/filedialogfactory.h
index 115d619d1..d5b790b18 100644
--- a/src/qmmpui/filedialogfactory.h
+++ b/src/qmmpui/filedialogfactory.h
@@ -36,7 +36,8 @@ public:
     {
         hasAbout = FALSE;
     }
-    bool hasAbout;      /*!< Should be \b true if the file dialog plugin has about dialog, otherwise \b false */
+    bool hasAbout;      /*!< Should be \b true if the file dialog plugin has about dialog, otherwise should be
+                         * \b false */
     QString name;       /*!< File dialog plugin full name */
     QString shortName;  /*!< File dialog short name for internal usage */
 };
diff --git a/src/qmmpui/fileloader.h b/src/qmmpui/fileloader.h
index e89f4a166..50899ccba 100644
--- a/src/qmmpui/fileloader.h
+++ b/src/qmmpui/fileloader.h
@@ -62,7 +62,7 @@ public:
     void setDirectoryToLoad(const QString&);
 signals:
     /*!
-     * Emited when new playlist item is available.
+     * Emitted when new playlist item is available.
      * @param item Pointer of the new PlayListItem object.
      */
     void newPlayListItem(PlayListItem *item);
diff --git a/src/qmmpui/general.h b/src/qmmpui/general.h
index e4f636354..244d02114 100644
--- a/src/qmmpui/general.h
+++ b/src/qmmpui/general.h
@@ -52,22 +52,22 @@ public:
     /*!
      * Sets whether the general plugin is enabled.
      * @param factory General plugin factory.
-     * @param enabled Plugin enable state (\b true - enable, \b false - disable)
+     * @param enable Plugin enable state (\b true - enable, \b false - disable)
      */
     static void setEnabled(GeneralFactory* factory, bool enable = TRUE);
     /*!
-     * Return \b true if general plugin is enabled, otherwise \b false
+     * Returns \b true if general plugin is enabled, otherwise returns \b false
      * @param factory General plugin factory.
      */
     static bool isEnabled(GeneralFactory* factory);
 
 signals:
     /*!
-     * Emited when exit() slot is called.
+     * Emitted when exit() slot is called.
      */
     void exitCalled();
     /*!
-     * Emited when toggleVisibility() slot is called.
+     * Emitted when toggleVisibility() slot is called.
      */
     void toggleVisibilityCalled();
 
diff --git a/src/qmmpui/generalfactory.h b/src/qmmpui/generalfactory.h
index c1bcc72ae..02fcedd57 100644
--- a/src/qmmpui/generalfactory.h
+++ b/src/qmmpui/generalfactory.h
@@ -42,12 +42,12 @@ public:
     }
     QString name;           /*!< File dialog plugin full name */
     QString shortName;      /*!< File dialog short name for internal usage */
-    bool hasAbout;          /*!< Should be \b true if plugin has about dialog, otherwise \b false */
-    bool hasSettings;       /*!< Should be \b true if plugin has settings dialog, otherwise \b false */
+    bool hasAbout;          /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */
+    bool hasSettings;       /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */
     bool visibilityControl; /*!< Should be \b true if plugin can show/hide main window of the player,
-                             * otherwise \b false */
+                             * otherwise returns \b false */
 };
-/*! @brief General plugin interface.
+/*! @brief %General plugin interface.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class GeneralFactory
diff --git a/src/qmmpui/generalhandler.h b/src/qmmpui/generalhandler.h
index 179c956d8..fa064f3ee 100644
--- a/src/qmmpui/generalhandler.h
+++ b/src/qmmpui/generalhandler.h
@@ -60,7 +60,7 @@ public:
     /*!
      * Sets whether the general plugin is enabled.
      * @param factory General plugin factory.
-     * @param enabled Plugin enable state (\b true - enable, \b false - disable)
+     * @param enable Plugin enable state (\b true - enable, \b false - disable)
      */
     void setEnabled(GeneralFactory* factory, bool enable);
     /*!
@@ -70,7 +70,7 @@ public:
      */
     void showSettings(GeneralFactory* factory, QWidget* parentWidget);
     /*!
-     * Returns \b true if one of the general plugin can change visibility, otherwise \b false
+     * Returns \b true if one of the general plugin can change visibility, otherwise returns \b false
      */
     bool visibilityControl();
     /*!
@@ -97,7 +97,7 @@ public:
      * Creates menu with type \b type
      * @param type Menu type.
      * @param title Menu title.
-     * @param paren Parent widget
+     * @param parent Parent widget
      */
     QMenu *createMenu(MenuType type, const QString &title = QString(), QWidget *parent = 0);
     /*!
@@ -107,12 +107,12 @@ public:
 
 signals:
     /*!
-     * Emited when some general plugin requires to exit.
+     * Emitted when some general plugin requires to exit.
      * Use it to quit application.
      */
     void exitCalled();
     /*!
-     * Emited when some general plugin requires to toggle visibility.
+     * Emitted when some general plugin requires to toggle visibility.
      * Use it to show/hide player's window.
      */
     void toggleVisibilityCalled();
diff --git a/src/qmmpui/mediaplayer.h b/src/qmmpui/mediaplayer.h
index 51d56a5f0..7c03bf3a3 100644
--- a/src/qmmpui/mediaplayer.h
+++ b/src/qmmpui/mediaplayer.h
@@ -56,7 +56,7 @@ public:
      */
     PlayListModel *playListModel();
     /*!
-     * Returns \b true if "Repeate Track" option is enabled, otherwise \b false
+     * Returns \b true if "Repeate Track" option is enabled, otherwise returns \b false
      */
     bool isRepeatable() const;
 
diff --git a/src/qmmpui/playlistitem.h b/src/qmmpui/playlistitem.h
index dd2898f64..5dc67d2df 100644
--- a/src/qmmpui/playlistitem.h
+++ b/src/qmmpui/playlistitem.h
@@ -64,8 +64,7 @@ public:
      */
     void setSelected(bool select);
     /*!
-     * Return \b true if item is selected, otherwise \b false.
-     *  @param yes State of current (\b true - set flag, \b false - unset flag)
+     * Return \b true if item is selected, otherwise returns \b false.
      */
     bool isSelected() const;
     /*!
@@ -73,7 +72,7 @@ public:
      */
     void setCurrent(bool yes);
     /*!
-     * Returns \b true if the item is the current item; otherwise returns \b false.
+     * Returns \b true if the item is the current item; otherwise returns returns \b false.
      */
     bool isCurrent() const;
     /*!
diff --git a/src/qmmpui/playlistmodel.h b/src/qmmpui/playlistmodel.h
index e22334b07..b3e89aef7 100644
--- a/src/qmmpui/playlistmodel.h
+++ b/src/qmmpui/playlistmodel.h
@@ -47,7 +47,7 @@ struct SimpleSelection
         ;
     }
     /*!
-     * Returns \p true if this selection is valid; otherwise returns \p false.
+     * Returns \p true if this selection is valid; otherwise returns returns \p false.
      */
     inline bool isValid()const
     {
@@ -67,10 +67,10 @@ struct SimpleSelection
     {
         return m_bottom - m_top + 1;
     }
-    int m_bottom;
-    int m_top;
-    int m_anchor;
-    QList<int>m_selected_rows;
+    int m_bottom;               /*!<    */
+    int m_top;                  /*!<    */
+    int m_anchor;               /*!<    */
+    QList<int>m_selected_rows;  /*!< Selected rows numbers */
 };
 /*! @internal
  * @brief Helper class used for tags update after details dialog closing.
@@ -132,12 +132,12 @@ public:
     int currentRow();
     /*!
      * Sets current row number.
-     * Returns \b false if item with this number doesn't exist, otherwise \b true
+     * Returns \b false if item with this number doesn't exist, otherwise returns \b true
      * @param row Number of item.
      */
     bool setCurrent (int row);
     /*!
-     * Returns \b true if \b row is selected, otherwise \b false
+     * Returns \b true if \b row is selected, otherwise returns \b false
      */
     bool isSelected(int row);
     /*!
@@ -148,12 +148,12 @@ public:
     void setSelected(int row, bool select);
     /*!
      * Advances to the next item. Returns \b false if next iten doesn't exist,
-     * otherwise \b true
+     * otherwise returns \b true
      */
     bool next();
     /*!
      * Goes back to the previous item. Returns \b false if previous iten doesn't exist,
-     * otherwise \b true
+     * otherwise returns \b true
      */
     bool previous();
     /*!
@@ -181,7 +181,7 @@ public:
      */
     void setCurrentToQueued();
     /*!
-     * Returns \b true if play queue is empty,otherwise - \b false.
+     * Returns \b true if play queue is empty,otherwise returns - \b false.
      */
     bool isEmptyQueue()const;
     /*!
@@ -339,7 +339,7 @@ public slots:
     /*!
      * Removes previous items and loads list of files (regular files or directories),
      * returns \b TRUE if at least one file has been successfully loaded,
-     * otherwise \b FALSE
+     * otherwise returns \b FALSE
      */
     bool setFileList(const QStringList &l);
     /*!
diff --git a/src/qmmpui/playlistparser.h b/src/qmmpui/playlistparser.h
index 7b9688a52..5197feefe 100644
--- a/src/qmmpui/playlistparser.h
+++ b/src/qmmpui/playlistparser.h
@@ -45,7 +45,7 @@ public:
      */
     QStringList getExtensions();
     /*!
-     * Returns \b true if file \b filePath is supported, otherwise \b false
+     * Returns \b true if file \b filePath is supported, otherwise returns \b false
      */
     bool supports(const QString &filePath);
     /*!
diff --git a/src/qmmpui/playstate.h b/src/qmmpui/playstate.h
index a2b525f7d..554afcf11 100644
--- a/src/qmmpui/playstate.h
+++ b/src/qmmpui/playstate.h
@@ -31,12 +31,12 @@ class PlayState
 {
 public:
     /*! Makes single step forward through songs list.
-     *  If the step has done returns \b true, otherwise \b false
+     *  If the step has done returns \b true, otherwise returns \b false
      */
     virtual bool next() = 0;
 
     /*! Makes single step back through songs list.
-     *  If the step has done returns \b true, otherwise \b false
+     *  If the step has done returns \b true, otherwise returns \b false
      */
     virtual bool previous() = 0;