output and visual api documentation

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

11 files changed, 260 insertions, 72 deletions

diff --git a/src/qmmp/decoder.h b/src/qmmp/decoder.h
index c9f52d56b..224ffc33e 100644
--- a/src/qmmp/decoder.h
+++ b/src/qmmp/decoder.h
@@ -77,7 +77,7 @@ public:
     virtual void stop() = 0;
     /*!
      * Requests playback to pause. If it was paused already, playback should resume.
-     * Subclass should reimplement this function.
+     * Subclass with own output should reimplement this function.
      */
     virtual void pause(){};
     /*!
@@ -93,7 +93,7 @@ public:
      */
     Output *output();
     /*!
-     * Returns Mutex pointer.
+     * Returns mutex pointer.
      */
     QMutex *mutex();
     /*!
diff --git a/src/qmmp/downloader.h b/src/qmmp/downloader.h
index aa952cda6..0ac96786d 100644
--- a/src/qmmp/downloader.h
+++ b/src/qmmp/downloader.h
@@ -29,9 +29,9 @@
 
 #define BUFFER_SIZE 128000 
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @internal
+ *   @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 struct Stream
 {
     char *buf;
@@ -42,7 +42,7 @@ struct Stream
     bool icy_meta_data;
     int icy_metaint;
 };
-/*!
+/*! @internal
  *  @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class Downloader : public QThread
diff --git a/src/qmmp/effect.h b/src/qmmp/effect.h
index 477bc631d..7d0e325b1 100644
--- a/src/qmmp/effect.h
+++ b/src/qmmp/effect.h
@@ -50,7 +50,7 @@ public:
      */
     virtual ulong process(char *in_data, const ulong size, char **out_data) = 0;
     /*!
-     * Prepares Effect object for usage.
+     * Prepares object for usage.
      * Subclasses that reimplement this function must call the base implementation.
      * @param freq Sample rate.
      * @param chan Number of channels.
@@ -62,15 +62,15 @@ public:
      */
     quint32 sampleRate();
     /*!
-     * Returns channel number.
+     * Returns channels number.
      */
     int channels();
     /*!
-     * Returns bit depth.
+     * Returns bits per sample.
      */
     int bitsPerSample();
     /*!
-     * Creates list of enabled effects.
+     * Creates a list of enabled effects.
      * @param parent Parent object of all created Effect objects.
      */
     static QList<Effect*> create(QObject *parent);
diff --git a/src/qmmp/effectfactory.h b/src/qmmp/effectfactory.h
index 883815c02..8ca8f2af2 100644
--- a/src/qmmp/effectfactory.h
+++ b/src/qmmp/effectfactory.h
@@ -57,18 +57,18 @@ public:
      */
     virtual const EffectProperties properties() const = 0;
     /*!
-     * Creates Effect object.
+     * Creates effect provided by plugin.
      * @param parent Parent object.
      */
     virtual Effect *create(QObject *parent) = 0;
     /*!
-     * Shows about dialog.
+     * Shows settings dialog.
      * @param parent Parent widget.
      */
     virtual void showSettings(QWidget *parent) = 0;
     /*!
-     * Creates QTranslator object of the system locale. Should return 0 if translation doesn't exist.
-     * @param parent Parent object.
+     * Shows about dialog.
+     * @param parent Parent widget.
      */
     virtual void showAbout(QWidget *parent) = 0;
     /*!
diff --git a/src/qmmp/output.h b/src/qmmp/output.h
index b1dfa28e0..7dab61180 100644
--- a/src/qmmp/output.h
+++ b/src/qmmp/output.h
@@ -24,41 +24,121 @@ class Output;
 
 class QTimer;
 
-/*!
- *  @author Brad Hughes <bhughes@trolltech.com>
+/*! @brief The Output class provides the base interface class of audio outputs.
+ * @author Brad Hughes <bhughes@trolltech.com>
+ * @author Ilya Kotov <forkotov@hotmail.ru>
  */
 class Output : public QThread
 {
     Q_OBJECT
 public:
-
+    /*!
+     * Object contsructor.
+     * @param parent Parent object.
+     */
     Output(QObject * parent = 0);
+    /*!
+     * Destructor.
+     */
     ~Output();
-
-      // abstract
+    /*!
+     * Prepares object for usage.
+     * Subclass should reimplement this function.
+     * @return initialization result (\b true - success, \b false - failure)
+     */
     virtual bool initialize() = 0;
+    /*!
+     * Returns output interface latency in milliseconds.
+     */
     virtual qint64 latency() = 0;
-    virtual void configure(quint32, int, int);
-
+    /*!
+     * Setups audio parameters of output interface.
+     * @param freq Sample rate.
+     * @param chan Number of channels.
+     * @param bits Bits per sample
+     */
+    virtual void configure(quint32 freq, int chan, int bits);
+    /*!
+     * Requests playback to pause. If it was paused already, playback should resume.
+     */
     void pause();
+    /*!
+     * Requests playback to stop.
+     */
     void stop();
+    /*!
+     * Returns the number of bytes that were written.
+     */
     qint64 written();
-    void seek(qint64);
+    /*!
+     * Requests a seek to the time \b pos indicated, specified in milliseconds.
+     */
+    void seek(qint64 pos);
+    /*!
+     * Returns Recycler pointer.
+     */
     Recycler *recycler();
+    /*!
+     * Returns mutex pointer.
+     */
     QMutex *mutex();
+    /*!
+     * Sets StateHandler pointer. May be used to override default state handler.
+     * @param hanlder StateHandler pointer;
+     */
     void setStateHandler(StateHandler *handler);
+    /*!
+     * Returns samplerate.
+     */
     quint32 sampleRate();
+    /*!
+     * Returns channels number.
+     */
     int numChannels();
+    /*!
+     * Returns bits per sample.
+     */
     int sampleSize();
-
-    static void registerFactory(OutputFactory *);
-    static Output *create(QObject *);
+    /*!
+     * Creates selected output.
+     * @param parent Parent object.
+     * @return Output subclass object.
+     */
+    static Output *create(QObject *parent);
+    /*!
+     * Returns a list of output factories.
+     */
     static QList<OutputFactory*> *outputFactories();
+    /*!
+     * Returns a list of output plugin file names.
+     */
     static QStringList outputFiles();
+    /*!
+     * Selects current output \b factory.
+     */
     static void setCurrentFactory(OutputFactory* factory);
+    /*!
+     * Returns selected output factory.
+     */
     static OutputFactory *currentFactory();
 
 protected:
+    /*!
+     * Writes up to \b maxSize bytes from \b data to the output interface device.
+     * Returns the number of bytes written, or -1 if an error occurred.
+     * Subclass should reimplement this function.
+     */
+    virtual qint64 writeAudio(unsigned char *data, qint64 maxSize) = 0;
+    /*!
+     * Writes all remaining plugin's internal data to audio output device.
+     * Subclass should reimplement this function.
+     */
+    virtual void flush() = 0;
+
+private:
+    void run(); //thread run function
+    void status();
+    void changeVolume(uchar *data, qint64 size, int chan);
     void dispatch(qint64 elapsed,
                   qint64 totalTime,
                   int bitrate,
@@ -68,14 +148,6 @@ protected:
     void dispatch(const Qmmp::State &state);
     void dispatchVisual(Buffer *, unsigned long, int, int);
     void clearVisuals();
-
-    virtual qint64 writeAudio(unsigned char *data, qint64 maxSize) = 0;
-    virtual void flush() = 0;
-
-private:
-    void run(); //thread run function
-    void status();
-    void changeVolume(uchar *data, qint64 size, int chan);
     QMutex m_mutex;
     Recycler m_recycler;
     StateHandler *m_handler;
@@ -86,6 +158,7 @@ private:
     qint64 m_totalWritten, m_currentMilliseconds;
 
     static void checkFactories();
+    static void registerFactory(OutputFactory *);
     //TODO use QMap instead
     static QList<OutputFactory*> *m_factories;
     static QStringList m_files;
diff --git a/src/qmmp/outputfactory.h b/src/qmmp/outputfactory.h
index b2dc621ca..f05332e64 100644
--- a/src/qmmp/outputfactory.h
+++ b/src/qmmp/outputfactory.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2007-2008 by Ilya Kotov                                 *
+ *   Copyright (C) 2007-2009 by Ilya Kotov                                 *
  *   forkotov02@hotmail.ru                                                 *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -27,37 +27,67 @@ class QIODevice;
 class QWidget;
 class QTranslator;
 class VolumeControl;
-
 class Decoder;
 class Output;
-/*!
- *  @author Ilya Kotov <forkotov02@hotmail.ru>
+
+/*! @brief Helper class to store output plugin properies.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class OutputProperties
 {
 public:
+    /*!
+     * Constructor
+     */
     OutputProperties()
     {
         hasAbout = FALSE;
         hasSettings = FALSE;
     }
-    QString name;
-    QString shortName;
-    bool hasAbout;
-    bool hasSettings;
+    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 */
 };
-/*!
- *  @author Ilya Kotov <forkotov02@hotmail.ru>
+/*! @brief Output plugin interface (output factory).
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class OutputFactory
 {
 public:
-    virtual ~OutputFactory() {} 
+    /*!
+     * Destructor.
+     */
+    virtual ~OutputFactory() {}
+    /*!
+     * Returns output plugin properties.
+     */
     virtual const OutputProperties properties() const = 0;
-    virtual Output *create(QObject *) = 0;
+    /*!
+     * Creates output provided by plugin.
+     * @param parent Parent object.
+     */
+    virtual Output *create(QObject *parent) = 0;
+    /*!
+     * Creates volume control object provided by plugin.
+     * Returns \b 0 if volume control is not supported by plugin.
+     * @param parent Parent object.
+     */
     virtual VolumeControl *createVolumeControl(QObject *) = 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/streamreader.h b/src/qmmp/streamreader.h
index d69a04dc6..e73f65389 100644
--- a/src/qmmp/streamreader.h
+++ b/src/qmmp/streamreader.h
@@ -28,9 +28,9 @@ class QFileInfo;
 
 class Downloader;
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @internal
+ *   @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class StreamReader : public QIODevice
 {
     Q_OBJECT
diff --git a/src/qmmp/visual.h b/src/qmmp/visual.h
index 6cbd370dc..f1b510899 100644
--- a/src/qmmp/visual.h
+++ b/src/qmmp/visual.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  *
@@ -30,38 +30,97 @@ class Decoder;
 class Output;
 class VisualFactory;
 
-/**
-   @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The Visual class provides the base interface class of visualizations.
+ *  @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class Visual : public QWidget
 {
     Q_OBJECT
 public:
+    /*!
+    * Object contsructor.
+    * @param parent Parent object.
+    */
     Visual(QWidget *parent);
-
+    /*!
+     * Destructor.
+     */
     virtual ~Visual();
-
-    virtual void add(Buffer *, unsigned long, int, int) = 0;
+    /*!
+     * Adds data for visualization.
+     * Subclass should reimplement this function.
+     * @param b Buffer object pointer.
+     * @param freq Samplerate.
+     * @param chan Number of channels
+     * @param bits Bits per sample.
+     */
+    virtual void add(Buffer *b, unsigned long freq, int chan, int bits) = 0;
+    /*!
+     * Resets visual plugin buffers and widgets.
+     * Subclass should reimplement this function.
+     */
     virtual void clear() = 0;
-    //virtual void stop() = 0;
+    /*!
+     * Returns mutex pointer.
+     */
     QMutex *mutex();
-
-    //static methods
+    /*!
+    * Returns a list of visual factories.
+    */
     static QList<VisualFactory*> *factories();
+    /*!
+     * Returns a list of visual plugin file names.
+     */
     static QStringList files();
+    /*!
+     * Sets whether the visual plugin is enabled.
+     * @param factory Visual plugin factory.
+     * @param enabled 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
+     * @param factory Effect plugin factory.
+     */
     static bool isEnabled(VisualFactory* factory);
-    static void add(Visual*);
+    /*!
+     * Adds external visualization \b visual.
+     */
+    static void add(Visual*visual);
+    /*!
+     * Removes external visualization \b visual.
+     */
     static void remove(Visual*);
+    /*!
+     * Prepares visual plugins for usage.
+     * @param parent Parent widget.
+     * @param receiver Receiver object.
+     * @param member A slot to receive changes of active visualizations list.
+     */
     static void initialize(QWidget *parent, QObject *receiver = 0, const char *member = 0);
-    static QList<Visual*>* visuals();
+    /*!
+     * Returns a pointer to a list of created visual objects.
+     */
+    static QList<Visual *> *visuals();
+    /*!
+     * Shows configuration dialog and updates settings automatically.
+     * @param factory Visual plugin factory.
+     * @param parent Parent widget.
+     */
     static void showSettings(VisualFactory *factory, QWidget *parent);
 
 signals:
+    /*!
+     * Emited when visual widget is closed by user.
+     */
     void closedByUser();
 
 protected:
-    virtual void closeEvent (QCloseEvent *);
+    /*!
+     * QWidget's close event. Reimplementation should call base function.
+     * @param event QCloseEvent insatance.
+     */
+    virtual void closeEvent (QCloseEvent *event);
 
 private:
     Decoder *m_decoder;
diff --git a/src/qmmp/visualfactory.h b/src/qmmp/visualfactory.h
index 74616de7c..1f631392f 100644
--- a/src/qmmp/visualfactory.h
+++ b/src/qmmp/visualfactory.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  *
@@ -25,35 +25,61 @@ class QObject;
 class QWidget;
 class QTranslator;
 class QDialog;
-
 class Visual;
-/*!
+
+/*! @brief Helper class to store visual plugin properies.
  *  @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class VisualProperties
 {
 public:
+    /*!
+     * Constructor
+     */
     VisualProperties()
     {
         hasAbout = FALSE;
         hasSettings = FALSE;
     }
-    QString name;
-    QString shortName;
-    bool hasAbout;
-    bool hasSettings;
+    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 */
 };
-/*!
- *  @author Ilya Kotov <forkotov02@hotmail.ru>
+/*! Visual plugin interface (visual factory).
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class VisualFactory
 {
 public:
+    /*!
+     * Destructor.
+     */
     virtual ~VisualFactory() {}
+     /*!
+     * Returns visual plugin properties.
+     */
     virtual const VisualProperties properties() const = 0;
+    /*!
+     * Creates visualization provided by plugin.
+     * @param parent Parent object.
+     */
     virtual Visual *create(QWidget *parent) = 0;
+    /*!
+     * Creates configuration dialog.
+     * @param parent Parent widget.
+     * @return Configuration dialog pointer.
+     */
     virtual QDialog *createConfigDialog(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 \b 0 if translation doesn't exist.
+     * @param parent Parent object.
+     */
     virtual QTranslator *createTranslator(QObject *parent) = 0;
 };
 
diff --git a/src/qmmp/volumecontrol.h b/src/qmmp/volumecontrol.h
index 746176e5a..5be1d253f 100644
--- a/src/qmmp/volumecontrol.h
+++ b/src/qmmp/volumecontrol.h
@@ -53,7 +53,7 @@ private:
     int m_left, m_right;
 
 };
-/*!
+/*! @internal
  *  @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class SoftwareVolume : public VolumeControl
diff --git a/src/qmmpui/generalfactory.h b/src/qmmpui/generalfactory.h
index 3e0838586..c1bcc72ae 100644
--- a/src/qmmpui/generalfactory.h
+++ b/src/qmmpui/generalfactory.h
@@ -77,7 +77,7 @@ public:
      */
     virtual void showAbout(QWidget *parent) = 0;
     /*!
-     * Creates QTranslator object of the system locale. Should return 0 if translation doesn't exist.
+     * Creates QTranslator object of the system locale. Should return \b 0 if translation doesn't exist.
      * @param parent Parent object.
      */
     virtual QTranslator *createTranslator(QObject *parent) = 0;