general plugin api documentation

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

5 files changed, 189 insertions, 52 deletions

diff --git a/src/qmmpui/filedialog.h b/src/qmmpui/filedialog.h
index 3c287fee7..c5ccff59b 100644
--- a/src/qmmpui/filedialog.h
+++ b/src/qmmpui/filedialog.h
@@ -30,7 +30,7 @@
 #include "filedialogfactory.h"
 
 
-/*! @brief The FileDialog class is the base interface class of file dialogs.
+/*! @brief The FileDialog class is the base interface class of the file dialogs.
  * @author Vladimir Kuznetsov <vovanec@gmail.com>
  */
 class FileDialog : public QObject
diff --git a/src/qmmpui/general.h b/src/qmmpui/general.h
index ae94288e2..e4f636354 100644
--- a/src/qmmpui/general.h
+++ b/src/qmmpui/general.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  *
@@ -23,40 +23,67 @@
 #include <QObject>
 #include <QStringList>
 #include <QMap>
-
 #include "generalfactory.h"
 
-class Control;
-
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The General class provides the basic functionality for the general plugin objects
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class General : public QObject
 {
     Q_OBJECT
 public:
+    /*!
+     * Object constructor,
+     * @param parent Parent object
+     */
     General(QObject *parent = 0);
-
+    /*!
+     * Destructor
+     */
     ~General();
-
-    //static methods
+    /*!
+     * Returns a list of the loaded general plugin factories.
+     */
     static QList<GeneralFactory*> *generalFactories();
+    /*!
+     * Returns a list of the loaded general plugin files.
+     */
     static QStringList generalFiles();
+    /*!
+     * Sets whether the general plugin is enabled.
+     * @param factory General plugin factory.
+     * @param enabled 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
+     * @param factory General plugin factory.
+     */
     static bool isEnabled(GeneralFactory* factory);
 
-public slots:
-    void exit();
-    void toggleVisibility();
-
 signals:
+    /*!
+     * Emited when exit() slot is called.
+     */
     void exitCalled();
+    /*!
+     * Emited when toggleVisibility() slot is called.
+     */
     void toggleVisibilityCalled();
 
+public slots:
+    /*!
+     * Tells the player to exit.
+     */
+    void exit();
+    /*!
+     * Toggles player window visibility.
+     */
+    void toggleVisibility();
+
 private:
     QMap <uint, QString> m_strValues;
     QMap <uint, uint> m_numValues;
-
 };
 
 #endif
diff --git a/src/qmmpui/generalfactory.h b/src/qmmpui/generalfactory.h
index f0c9c61e3..270e07c9b 100644
--- a/src/qmmpui/generalfactory.h
+++ b/src/qmmpui/generalfactory.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  *
@@ -20,44 +20,68 @@
 #ifndef GENERALFACTORY_H
 #define GENERALFACTORY_H
 
-/**
-	@author Ilya Kotov <forkotov02@hotmail.ru>
-*/
 class QObject;
 class QTranslator;
 class QDialog;
 class Control;
-
 class General;
 
+/*! @brief Helper class to store general plugin properies.
+ */
 class GeneralProperties
 {
 public:
+    /*!
+     * Constructor
+     */
     GeneralProperties()
     {
         hasAbout = FALSE;
         hasSettings = FALSE;
         visibilityControl = FALSE;
     }
-    QString name;
-    QString shortName;
-    bool hasAbout;
-    bool hasSettings;
-    bool visibilityControl;
+    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 visibilityControl; /*!< Should be \b true if plugin can show/hide main window of the player,
+                             * otherwise \b false */
 };
-
+/*! @brief General plugin interface.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class GeneralFactory
 {
 public:
+    /*!
+     * Object destructor.
+     */
     virtual ~GeneralFactory() {}
+    /*!
+     * Returns general plugin properties.
+     */
     virtual const GeneralProperties properties() const = 0;
+    /*!
+     * Creates object of the General class.
+     */
     virtual General *create(QObject *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 0 if translation doesn't exist.
+     * @param parent Parent object.
+     */
     virtual QTranslator *createTranslator(QObject *parent) = 0;
 };
 
 Q_DECLARE_INTERFACE(GeneralFactory, "GeneralFactory/1.0");
-
-
 #endif
diff --git a/src/qmmpui/generalhandler.h b/src/qmmpui/generalhandler.h
index 295a2dd9c..563ff3f09 100644
--- a/src/qmmpui/generalhandler.h
+++ b/src/qmmpui/generalhandler.h
@@ -28,45 +28,93 @@
 class QAction;
 class QMenu;
 class QWidget;
-
 class General;
 class Control;
 class GeneralFactory;
 class CommandLineManager;
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
-
-//TODO add documentation
+/*! @brief The GeneralHandler class provied simple api to access general and command line plugins.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class GeneralHandler : public QObject
 {
     Q_OBJECT
 public:
+    /*!
+     * Object constructor,
+     * @param parent Parent object
+     */
     GeneralHandler(QObject *parent = 0);
-
+    /*!
+     * Destructor
+     */
     ~GeneralHandler();
-
+    /*!
+     * Enum of menu type
+     */
     enum MenuType
     {
-        TOOLS_MENU = 0,
-        PLAYLIST_MENU
+        TOOLS_MENU = 0, /*!< tools menu */
+        PLAYLIST_MENU   /*!< playlist context menu */
     };
-
+    /*!
+     * Sets whether the general plugin is enabled.
+     * @param factory General plugin factory.
+     * @param enabled Plugin enable state (\b true - enable, \b false - disable)
+     */
     void setEnabled(GeneralFactory* factory, bool enable);
+    /*!
+     * Shows configuration dialog and updates settings automatically.
+     * @param factory General plugin factory.
+     * @param parentWidget Parent widget.
+     */
     void showSettings(GeneralFactory* factory, QWidget* parentWidget);
+    /*!
+     * Returns \b true if one of the general plugin can change visibility, otherwise \b false
+     */
     bool visibilityControl();
+    /*!
+     * Executes command by command line plugins
+     * @param opt_str Command line option string
+     */
     void executeCommand(const QString &opt_str);
-    //actions
+    /*!
+     * Adds the newly created action to the menu with type \b type.
+     * Menu with type \b type should be created first.
+     * @param action Pointer of action.
+     * @param type Menu type.
+     */
     void addAction(QAction *action, MenuType type = TOOLS_MENU);
+    /*!
+     * Removes action \b action from created menus.
+     */
     void removeAction(QAction *action);
+    /*!
+     * Returns a list of actions of the menu type \b type
+     */
     QList<QAction *> actions(MenuType type = TOOLS_MENU);
+    /*!
+     * Creates menu with type \b type
+     * @param type Menu type.
+     * @param title Menu title.
+     * @param paren Parent widget
+     */
     QMenu *createMenu(MenuType type, const QString &title = QString(), QWidget *parent = 0);
-
+    /*!
+     * Returns a pointer to the object's instance.
+     */
     static GeneralHandler* instance();
 
 signals:
+    /*!
+     * Emited when some general plugin requires to exit.
+     * Use it to quit application.
+     */
     void exitCalled();
+    /*!
+     * Emited when some general plugin requires to toggle visibility.
+     * Use it to show/hide player's window.
+     */
     void toggleVisibilityCalled();
 
 private slots:
diff --git a/src/qmmpui/mediaplayer.h b/src/qmmpui/mediaplayer.h
index cb52ffa37..a595b8453 100644
--- a/src/qmmpui/mediaplayer.h
+++ b/src/qmmpui/mediaplayer.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,32 +25,70 @@
 class PlayListModel;
 class SoundCore;
 
-/**
-	@author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The MediaPlayer class provides a simple way to use SoundCore and PlayListModel together.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class MediaPlayer : public QObject
 {
-Q_OBJECT
+    Q_OBJECT
 public:
+    /*!
+     * Object constructor,
+     * @param parent Parent object
+     */
     MediaPlayer(QObject *parent = 0);
-
+    /*!
+     * Destructor
+     */
     ~MediaPlayer();
-
+    /*!
+     * Returns a pointer to the object's instance.
+     */
     static MediaPlayer* instance();
-
+    /*!
+     * Prepares object for usage.
+     * @param core Pointer to the SoundCore object.
+     * @param model Playlist model
+     */
     void initialize(SoundCore *core, PlayListModel *model);
+    /*!
+     * Returns playlist model pointer
+     */
     PlayListModel *playListModel();
+    /*!
+     * Returns \b true if "Repeate Track" option is enabled, otherwise \b false
+     */
     bool isRepeatable() const;
 
 public slots:
+    /*!
+     * Starts playback.
+     */
     void play();
+    /*!
+     * Stops playback.
+     */
     void stop();
+    /*!
+     * Sets next playlist item for playing.
+     */
     void next();
+    /*!
+     * Sets previous playlist item for playing.
+     */
     void previous();
-    void setRepeatable(bool);
+    /*!
+     * Toggles the current track repeat.
+     * @param enable Repeate state of the current track (\b true - to repeat, \b false - to stop repeating)
+     */
+    void setRepeatable(bool enable);
 
 signals:
-    void repeatableChanged(bool);
+    /*!
+     * Tracks current track repeat state;
+     * @param enabled New repeate state of the current track (\b true - enabled, \b false - disabled)
+     */
+    void repeatableChanged(bool enabled);
 
 private:
     PlayListModel *m_model;