decoder api documentation

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

15 files changed, 248 insertions, 71 deletions

diff --git a/src/qmmp/buffer.h b/src/qmmp/buffer.h
index c5ffadc0c..6c9e84f21 100644
--- a/src/qmmp/buffer.h
+++ b/src/qmmp/buffer.h
@@ -9,6 +9,10 @@
 
 #include "constants.h"
 
+/*!
+ * @author Brad Hughes <bhughes@trolltech.com>
+ */
+
 class Buffer
 {
 public:
diff --git a/src/qmmp/decoder.cpp b/src/qmmp/decoder.cpp
index 64b5b33af..3a6cde240 100644
--- a/src/qmmp/decoder.cpp
+++ b/src/qmmp/decoder.cpp
@@ -238,19 +238,6 @@ void Decoder::checkFactories()
     }
 }
 
-QStringList Decoder::all()
-{
-    checkFactories();
-
-    QStringList l;
-    DecoderFactory *fact;
-    foreach(fact, *m_factories)
-    {
-        l << fact->properties().description;
-    }
-    return l;
-}
-
 QStringList Decoder::files()
 {
     checkFactories();
diff --git a/src/qmmp/decoder.h b/src/qmmp/decoder.h
index d4190e733..a9553cf8f 100644
--- a/src/qmmp/decoder.h
+++ b/src/qmmp/decoder.h
@@ -15,12 +15,10 @@
 #include <QStringList>
 #include <QUrl>
 #include <QList>
-
 #include "fileinfo.h"
 
 class QObject;
 class QIODevice;
-
 class Decoder;
 class DecoderFactory;
 class Buffer;
@@ -30,56 +28,179 @@ class Visualization;
 class Effect;
 class StateHandler;
 
-
+/*! @brief The Decoder class provides the base interface class of audio decoders.
+ * @author Brad Hughes <bhughes@trolltech.com>
+ * @author Ilya Kotov <forkotov@hotmail.ru>
+ */
 class Decoder : public QThread
 {
     Q_OBJECT
 public:
+    /*!
+     * Object contsructor for decoders with QIODevice-based input.
+     * @param parent Parent object.
+     * @param d Decoder's factory object.
+     * @param input QIODevice-based input source.
+     * @param output Output object.
+     */
     Decoder(QObject *parent, DecoderFactory *d, QIODevice *input = 0, Output *output = 0);
+    /*!
+     * Object contsructor for decoders without QIODevice-based input.
+     * @param parent Parent object.
+     * @param d Decoder's factory object.
+     * @param output Output object.
+     */
     Decoder(QObject *parent, DecoderFactory *d, Output *output);
-
+    /*!
+     * Destructor.
+     */
     virtual ~Decoder();
-
-    // Standard Decoder API
+    /*!
+     * Prepares decoder for usage.
+     * Subclass should reimplement this function.
+     */
     virtual bool initialize() = 0;
+    /*!
+     * Returns the total time in milliseconds.
+     * Subclass should reimplement this function.
+     */
     virtual qint64 totalTime() = 0;
-    virtual void seek(qint64) = 0;
+    /*!
+     * Requests a seek to the time \b time indicated, specified in milliseconds.
+     * Subclass should reimplement this function.
+     */
+    virtual void seek(qint64 time) = 0;
+    /*!
+     * Requests playback to stop
+     * Subclass should reimplement this function.
+     */
     virtual void stop() = 0;
+    /*!
+     * Requests playback to pause. If it was paused already, playback should resume.
+     * Subclass should reimplement this function.
+     */
     virtual void pause(){};
-
+    /*!
+     * Returns decoder's factory object.
+     */
     DecoderFactory *factory() const;
+    /*!
+     * Returns decoder input or 0 if input is not specified.
+     */
     QIODevice *input();
+    /*!
+     * Returns decoder output or 0 if output is not specified.
+     */
     Output *output();
+    /*!
+     * Returns Mutex pointer.
+     */
     QMutex *mutex();
+    /*!
+     * Returns wait condition pointer.
+     */
     QWaitCondition *cond();
+    /*!
+     * Returns StateHandler object pointer.
+     */
     StateHandler *stateHandler();
-
+    /*!
+     * Sets StateHandler pointer. May be used to override default state handler.
+     * @param hanlder StateHandler pointer;
+     */
     void setStateHandler(StateHandler *handler);
+    /*!
+     * 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.
+     */
     virtual void setEQ(double bands[10], double preamp);
+    /*!
+     * 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.
+     */
     virtual void setEQEnabled(bool on);
-
-    // static methods
-    static QStringList all();
-    static bool supports(const QString &);
-    static DecoderFactory *findByPath(const QString&);
-    static DecoderFactory *findByMime(const QString&);
-    static DecoderFactory *findByContent(QIODevice *);
+    /*!
+     * Returns \b true if \b file is supported by input plugins, otherwise \b false
+     */
+    static bool supports(const QString &file);
+    /*!
+     * Returns DecoderFactory pointer which supports file \b path or 0 if file \b path is unsupported
+     */
+    static DecoderFactory *findByPath(const QString &path);
+    /*!
+     * Returns DecoderFactory pointer which supports mime type \b mime or \b 0 if mime type \b mime is unsupported
+     */
+    static DecoderFactory *findByMime(const QString &mime);
+    /*!
+     * Returns DecoderFactory pointer which supports data provided by QIODevice \b input
+     * or \b 0 if data is unsupported.
+     */
+    static DecoderFactory *findByContent(QIODevice *input);
+    /*!
+     * Returns DecoderFactory pointer which supports \b url or \b 0 if \b url is not supported.
+     */
     static DecoderFactory *findByURL(const QUrl &url);
-    static QList <FileInfo *> createPlayList(const QString &fileName, bool useMetaData = TRUE);
+    /*!
+     * Extracts metadata and audio information from file \b path and returns a list of FileInfo items.
+     * One file may contain several playlist items (for example: cda disk or flac with embedded cue)
+     * @param path Source file path.
+     * @param useMetaData Metadata usage (\b true - use, \b - do not use)
+     */
+    static QList <FileInfo *> createPlayList(const QString &path, bool useMetaData = TRUE);
+    /*!
+     * Returns a list of file name filters with description, i.e. "MPEG Files (*.mp3 *.mpg)"
+     */
     static QStringList filters();
+    /*!
+     * Returns a list of file name filters, i.e. "*.mp3 *.mpg"
+     */
     static QStringList nameFilters();
+    /*!
+     * Returns a list of decoder factories.
+     */
     static QList<DecoderFactory*> *factories();
+    /*!
+     * Returns a list of input plugin file names.
+     */
     static QStringList files();
+    /*!
+     * Sets whether the input plugin is enabled.
+     * @param factory Decoder plugin factory.
+     * @param enabled Plugin enable state (\b true - enable, \b false - disable)
+     */
     static void setEnabled(DecoderFactory* factory, bool enable = TRUE);
+    /*!
+     * Return \b true if input plugin is enabled, otherwise \b false
+     * @param factory Decoder plugin factory.
+     */
     static bool isEnabled(DecoderFactory* factory);
 
 signals:
+    /*!
+     * Emitted when the decoder has finished playback.
+     */
     void playbackFinished();
 
 protected:
+    /*!
+     * Use this function inside initialize() reimplementation to tell other plugins about audio parameters.
+     * @param srate Sample rate.
+     * @param chan Number of channels.
+     * @param bps Bits per sample.
+     */
     void configure(quint32 srate, int chan, int bps);
+    /*!
+     * Sends audio data to the output plugin.
+     * @param data Pointer to audio data.
+     * @param size Audio data size.
+     * @param chan Number of channels.
+     */
     qint64 produceSound(char *data, qint64 size, quint32 brate, int chan);
+
 protected slots:
+    /*!
+     * Subclass should call this slot when decoding is finished.
+     */
     void finish();
 
 private:
diff --git a/src/qmmp/decoderfactory.h b/src/qmmp/decoderfactory.h
index b36b48815..d9d83d24a 100644
--- a/src/qmmp/decoderfactory.h
+++ b/src/qmmp/decoderfactory.h
@@ -1,6 +1,5 @@
-
 /***************************************************************************
- *   Copyright (C) 2006 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  *
@@ -32,9 +31,15 @@ class Decoder;
 class Output;
 class FileInfo;
 
+/*! @brief Helper class to store input plugin properies.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class DecoderProperties
 {
 public:
+    /*!
+     * Constructor
+     */
     DecoderProperties()
     {
         hasAbout = FALSE;
@@ -43,32 +48,76 @@ public:
         noOutput = FALSE;
 
     }
-    QString name;
-    QString shortName;
-    QString filter;
-    QString description;
-    QString contentType;
-    QString protocols;
-    bool hasAbout;
-    bool hasSettings;
-    bool noInput;
-    bool noOutput;
+    QString name;        /*!< Input plugin full name */
+    QString shortName;   /*!< Input plugin short name for internal usage */
+    QString filter;      /*!< File filter (example: "*.mp3 *.ogg") */
+    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 */
 };
-
+/*! @brief Input plugin interface.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class DecoderFactory
 {
 public:
+    /*!
+    * Object destructor.
+    */
     virtual ~DecoderFactory() {}
+    /*!
+     * Returns \b true if plugin supports \b source, otherwise \b false
+     */
     virtual bool supports(const QString &source) const = 0;
-    virtual bool canDecode(QIODevice *) const = 0;
+    /*!
+     * Returns \b true if plugin can decode data provided by \b d, otherwise \b false
+     */
+    virtual bool canDecode(QIODevice *d) const = 0;
+    /*!
+     * Returns general plugin properties.
+     */
     virtual const DecoderProperties properties() const = 0;
-    virtual Decoder *create(QObject *, QIODevice *input = 0,
+    /*!
+     * Creates decoder object.
+     * @param parent Parent object.
+     * @param input Input data (if required)
+     * @param output Output object (if required)
+     * @param path File path
+     */
+    virtual Decoder *create(QObject *parent, QIODevice *input = 0,
                             Output *output = 0, const QString &path = QString()) = 0;
-    //virtual FileInfo *createFileInfo(const QString &source) = 0;
+    /*!
+     * Extracts metadata and audio information from file \b path and returns a list of FileInfo items.
+     * One file may contain several playlist items (for example: cda disk or flac with embedded cue)
+     * @param fileName File path.
+     * @param useMetaData Metadata usage (\b true - use, \b - do not use)
+     */
     virtual QList<FileInfo *> createPlayList(const QString &fileName, bool useMetaData) = 0;
+    /*!
+     * Shows details dialog.
+     * @param parent Parent widget.
+     * @param path File path.
+     * @return Dialog pointer.
+     */
     virtual QObject* showDetails(QWidget *parent, const QString &path) = 0;
+    /*!
+     * Shows settings dialog.
+     * @param parent Parent widget.
+     */
     virtual void showSettings(QWidget *parent) = 0;
+    /*!
+     * Shows about dialog.
+     * @param parent Parent widget.
+     */
     virtual void showAbout(QWidget *parent) = 0;
+    /*!
+     * Creates QTranslator object of the system locale. Should return 0 if translation doesn't exist.
+     * @param parent Parent object.
+     */
     virtual QTranslator *createTranslator(QObject *parent) = 0;
 };
 
diff --git a/src/qmmp/downloader.h b/src/qmmp/downloader.h
index 94f5a2547..aa952cda6 100644
--- a/src/qmmp/downloader.h
+++ b/src/qmmp/downloader.h
@@ -32,7 +32,6 @@
 /**
     @author Ilya Kotov <forkotov02@hotmail.ru>
 */
-
 struct Stream
 {
     char *buf;
@@ -43,7 +42,9 @@ struct Stream
     bool icy_meta_data;
     int icy_metaint;
 };
-
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class Downloader : public QThread
 {
     Q_OBJECT
diff --git a/src/qmmp/effect.h b/src/qmmp/effect.h
index 20ac73b43..134c9eea7 100644
--- a/src/qmmp/effect.h
+++ b/src/qmmp/effect.h
@@ -25,12 +25,12 @@
 #include <QStringList>
 
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
 
-class EffectFactory;
 
+class EffectFactory;
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class Effect : public QObject
 {
     Q_OBJECT
diff --git a/src/qmmp/effectfactory.h b/src/qmmp/effectfactory.h
index 18f605eed..208990cb4 100644
--- a/src/qmmp/effectfactory.h
+++ b/src/qmmp/effectfactory.h
@@ -30,7 +30,9 @@ class QWidget;
 class QTranslator;
 
 class Effect;
-
+/*!
+ *   @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class EffectProperties
 {
 public:
@@ -44,7 +46,9 @@ public:
     bool hasAbout;
     bool hasSettings;
 };
-
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class EffectFactory
 {
 public:
diff --git a/src/qmmp/output.h b/src/qmmp/output.h
index 24056adbd..b1dfa28e0 100644
--- a/src/qmmp/output.h
+++ b/src/qmmp/output.h
@@ -24,7 +24,9 @@ class Output;
 
 class QTimer;
 
-
+/*!
+ *  @author Brad Hughes <bhughes@trolltech.com>
+ */
 class Output : public QThread
 {
     Q_OBJECT
diff --git a/src/qmmp/outputfactory.h b/src/qmmp/outputfactory.h
index c4522ea2a..b2dc621ca 100644
--- a/src/qmmp/outputfactory.h
+++ b/src/qmmp/outputfactory.h
@@ -30,7 +30,9 @@ class VolumeControl;
 
 class Decoder;
 class Output;
-
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class OutputProperties
 {
 public:
@@ -44,7 +46,9 @@ public:
     bool hasAbout;
     bool hasSettings;
 };
-
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class OutputFactory
 {
 public:
diff --git a/src/qmmp/recycler.h b/src/qmmp/recycler.h
index 6bb80375d..d73e08702 100644
--- a/src/qmmp/recycler.h
+++ b/src/qmmp/recycler.h
@@ -12,7 +12,9 @@
 
 class Buffer;
 
-
+/*!
+ *  @author Brad Hughes <bhughes@trolltech.com>
+ */
 class Recycler
 {
 public:
diff --git a/src/qmmp/soundcore.h b/src/qmmp/soundcore.h
index 75d8e4f47..c34d9cb3a 100644
--- a/src/qmmp/soundcore.h
+++ b/src/qmmp/soundcore.h
@@ -29,14 +29,12 @@
 #include "visual.h"
 #include "qmmp.h"
 
-/**
-   \author Ilya Kotov <forkotov02\hotmail.ru>
-*/
-
 class QIODevice;
-
 class VolumeControl;
 
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class SoundCore : public QObject
 {
     Q_OBJECT
diff --git a/src/qmmp/visual.h b/src/qmmp/visual.h
index e4159db46..6cbd370dc 100644
--- a/src/qmmp/visual.h
+++ b/src/qmmp/visual.h
@@ -20,10 +20,6 @@
 #ifndef VISUAL_H
 #define VISUAL_H
 
-/**
-   @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
-
 #include <QMutex>
 #include <QStringList>
 #include <QWidget>
@@ -34,6 +30,9 @@ class Decoder;
 class Output;
 class VisualFactory;
 
+/**
+   @author Ilya Kotov <forkotov02@hotmail.ru>
+*/
 class Visual : public QWidget
 {
     Q_OBJECT
diff --git a/src/qmmp/visualfactory.h b/src/qmmp/visualfactory.h
index d57b5cf55..74616de7c 100644
--- a/src/qmmp/visualfactory.h
+++ b/src/qmmp/visualfactory.h
@@ -27,7 +27,9 @@ class QTranslator;
 class QDialog;
 
 class Visual;
-
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class VisualProperties
 {
 public:
@@ -41,7 +43,9 @@ public:
     bool hasAbout;
     bool hasSettings;
 };
-
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class VisualFactory
 {
 public:
diff --git a/src/qmmp/volumecontrol.h b/src/qmmp/volumecontrol.h
index 5fa17ce78..746176e5a 100644
--- a/src/qmmp/volumecontrol.h
+++ b/src/qmmp/volumecontrol.h
@@ -53,7 +53,9 @@ private:
     int m_left, m_right;
 
 };
-
+/*!
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class SoftwareVolume : public VolumeControl
 {
     Q_OBJECT
diff --git a/src/qmmpui/generalfactory.h b/src/qmmpui/generalfactory.h
index 270e07c9b..3e0838586 100644
--- a/src/qmmpui/generalfactory.h
+++ b/src/qmmpui/generalfactory.h
@@ -43,7 +43,7 @@ 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 settingd dialog, otherwise \b false */
+    bool hasSettings;       /*!< Should be \b true if plugin has settings dialog, otherwise \b false */
     bool visibilityControl; /*!< Should be \b true if plugin can show/hide main window of the player,
                              * otherwise \b false */
 };