updated API documentation

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

11 files changed, 74 insertions, 33 deletions

diff --git a/src/qmmp/cueparser.h b/src/qmmp/cueparser.h
index 03cdec531..ccedb336b 100644
--- a/src/qmmp/cueparser.h
+++ b/src/qmmp/cueparser.h
@@ -57,7 +57,7 @@ public:
     /*!
      * Parses CUE file content.
      * \param data Content of CUE file.
-     * \param codecName Codec.
+     * \param codec Codec.
      */
     void loadData(const QByteArray &data, QTextCodec *codec);
     /*!
diff --git a/src/qmmp/inputsource.h b/src/qmmp/inputsource.h
index b40a48277..ddc9ced60 100644
--- a/src/qmmp/inputsource.h
+++ b/src/qmmp/inputsource.h
@@ -69,6 +69,10 @@ public:
      * Returns content type of the input stream. Default implementation returns empty string.
      */
     virtual QString contentType() const;
+    /*!
+     * Stops long operation (reading, seeking) from another thead, if necessary. Default implementation
+     * does nothing.
+     */
     virtual void stop();
     /*!
      * Returns input source path or url.
diff --git a/src/qmmp/metadatamodel.h b/src/qmmp/metadatamodel.h
index e67df57ac..5deea69f4 100644
--- a/src/qmmp/metadatamodel.h
+++ b/src/qmmp/metadatamodel.h
@@ -87,7 +87,7 @@ public:
     {
         IsCoverEditable = 0x1,      /*!< Enable cover editor. */
         CompletePropertyList = 0x2, /*!< Show properties from \b extraProperties() only (ignore other sources) */
-        IsCueEditable = 0x4
+        IsCueEditable = 0x4         /*!< Enable CUE editor. */
     };
     Q_DECLARE_FLAGS(DialogHints, DialogHint)
     /*!
@@ -135,8 +135,17 @@ public:
      * Returns path to cover pixmap.
      */
     virtual QString coverPath() const;
+    /*!
+     * Returns CUE file or tag content if necessary. Default implementation returns empty string.
+     */
     virtual QString cue() const;
+    /*!
+     * Updates CUE file or tag content. Default implementation doesn nothing.
+     */
     virtual void setCue(const QString &content);
+    /*!
+     * Removes CUE file or tag. Default implementation doesn nothing.
+     */
     virtual void removeCue();
     /*!
      * Returns \b true if file is opened in read only mode. Otherwise returns \b false.
diff --git a/src/qmmpui/detailsdialog.h b/src/qmmpui/detailsdialog.h
index 9b380e537..73f3d010c 100644
--- a/src/qmmpui/detailsdialog.h
+++ b/src/qmmpui/detailsdialog.h
@@ -54,10 +54,16 @@ public:
      * Destructor.
      */
     ~DetailsDialog();
-
+    /*!
+     * Returns a list of the modified file paths or track URLs.
+     */
     QStringList modifiedPaths() const;
 
 signals:
+    /*!
+     * Emitted when closed dialog has modified file paths or track URLs.
+     * @param paths A list of the modified file paths or track URLs.
+     */
     void metaDataChanged(const QStringList &paths);
 
 private slots:
diff --git a/src/qmmpui/general.cpp b/src/qmmpui/general.cpp
index 4d863ae74..81a903da4 100644
--- a/src/qmmpui/general.cpp
+++ b/src/qmmpui/general.cpp
@@ -178,12 +178,12 @@ void General::setEnabled(GeneralFactory *factory, bool enable)
             m_generals->insert(factory, general);
 
         for(const WidgetDescription &d : factory->properties().widgets)
-            UiHelper::instance()->addWidget(QString("%1_%2").arg(factory->properties().shortName).arg(d.id));
+            UiHelper::instance()->widgetAdded(QString("%1_%2").arg(factory->properties().shortName).arg(d.id));
     }
     else
     {
         for(const WidgetDescription &d : factory->properties().widgets)
-            UiHelper::instance()->removeWidget(QString("%1_%2").arg(factory->properties().shortName).arg(d.id));
+            UiHelper::instance()->widgetRemoved(QString("%1_%2").arg(factory->properties().shortName).arg(d.id));
 
         if(m_generals->value(factory))
             delete m_generals->take(factory);
@@ -206,7 +206,7 @@ void General::showSettings(GeneralFactory *factory, QWidget *parentWidget)
             m_generals->insert(factory, general);
 
         for(const WidgetDescription &d : factory->properties().widgets)
-            UiHelper::instance()->updateWidget(QString("%1_%2").arg(factory->properties().shortName).arg(d.id));
+            UiHelper::instance()->widgetUpdated(QString("%1_%2").arg(factory->properties().shortName).arg(d.id));
     }
     dialog->deleteLater();
 }
diff --git a/src/qmmpui/general.h b/src/qmmpui/general.h
index 0e9a4830f..554873188 100644
--- a/src/qmmpui/general.h
+++ b/src/qmmpui/general.h
@@ -47,8 +47,21 @@ public:
      * Returns a list of the enabled general plugin factories.
      */
     static QList<GeneralFactory *> enabledFactories();
+    /*!
+     * Returns a list of the enabled widget IDs.
+     */
     static QStringList enabledWidgets();
+    /*!
+     * Returns widget description.
+     * @param id Widget ID.
+     */
     static WidgetDescription widgetDescription(const QString &id);
+    /*!
+     * Creates widget provided by general plugin. May return \b nullptr
+     * if widget ID is not found.
+     * \param id Widget ID.
+     * \param parent Parent Widget.
+     */
     static QWidget *createWidget(const QString &id, QWidget *parent);
     /*!
      * Returns plugin file path.
diff --git a/src/qmmpui/generalfactory.h b/src/qmmpui/generalfactory.h
index 9e31c6a38..909496023 100644
--- a/src/qmmpui/generalfactory.h
+++ b/src/qmmpui/generalfactory.h
@@ -29,13 +29,15 @@ class QWidget;
 class Control;
 class General;
 
+/*! @brief Structure to store widget description provided by general plugin.
+ */
 struct WidgetDescription
 {
-    int id;
-    QString name;
-    QString shortcut;
-    Qt::DockWidgetArea area;
-    Qt::DockWidgetAreas allowedAreas;
+    int id;                           /*!< Widget ID */
+    QString name;                     /*!< Widget name (translatable) */
+    QString shortcut;                 /*!< Default key shortcut */
+    Qt::DockWidgetArea area;          /*!< Default area */
+    Qt::DockWidgetAreas allowedAreas; /*!< Allowed areas */
 };
 
 
@@ -70,6 +72,11 @@ public:
      * Creates object of the General class.
      */
     virtual QObject *create(QObject *parent) = 0;
+    /*!
+     * Creates widget provided by plugin. Default emplementation returns \b nullptr.
+     * \param id Widget ID.
+     * \param parent Parent Widget.
+     */
     virtual QWidget *createWidget(int id, QWidget *parent);
     /*!
      * Creates configuration dialog.
diff --git a/src/qmmpui/playlistmodel.h b/src/qmmpui/playlistmodel.h
index 2703e4171..e0e5376d1 100644
--- a/src/qmmpui/playlistmodel.h
+++ b/src/qmmpui/playlistmodel.h
@@ -414,6 +414,10 @@ public slots:
      * Inserts \b tracks at index position \b index in the playlist.
      */
     void insert(int index, const QList<PlayListTrack *> &tracks);
+    /*!
+     * Inserts serialized content \b json at index position \b index in the playlist.
+     * May be useful for fast drag-and-drop.
+     */
     void insert(int index, const QByteArray &json);
     /*!
      * Inserts \b tracks after item \b before in the playlist.
diff --git a/src/qmmpui/playlistparser.h b/src/qmmpui/playlistparser.h
index 0778a6ff0..941f6e0a7 100644
--- a/src/qmmpui/playlistparser.h
+++ b/src/qmmpui/playlistparser.h
@@ -88,8 +88,15 @@ public:
      * Loads all playlist plugins. Should be called before usage from another thread.
      */
     static void loadFormats();
-
+    /*!
+     * Converts track list \b tracks to JSON.
+     * May be useful for fast drag-and-drop.
+     */
     static QByteArray serialize(const QList<PlayListTrack *> &tracks);
+    /*!
+     * Converts JSON data \b json to track list.
+     * May be useful for fast drag-and-drop.
+     */
     static QList<PlayListTrack *> deserialize(const QByteArray &json);
 
 private:
diff --git a/src/qmmpui/uihelper.cpp b/src/qmmpui/uihelper.cpp
index 7e60b6458..e4a5f6e78 100644
--- a/src/qmmpui/uihelper.cpp
+++ b/src/qmmpui/uihelper.cpp
@@ -132,21 +132,6 @@ void UiHelper::registerMenu(UiHelper::MenuType type, QMenu *menu, bool autoHide,
     m_menus[type].menu->menuAction()->setVisible(!autoHide || !m_menus[type].actions.isEmpty());
 }
 
-void UiHelper::addWidget(const QString &id)
-{
-    emit widgetAdded(id);
-}
-
-void UiHelper::removeWidget(const QString &id)
-{
-    emit widgetRemoved(id);
-}
-
-void UiHelper::updateWidget(const QString &id)
-{
-    emit widgetUpdated(id);
-}
-
 void UiHelper::addFiles(QWidget *parent, PlayListModel *model)
 {
     QStringList filters;
diff --git a/src/qmmpui/uihelper.h b/src/qmmpui/uihelper.h
index ca5bfba75..f0a502a26 100644
--- a/src/qmmpui/uihelper.h
+++ b/src/qmmpui/uihelper.h
@@ -98,11 +98,6 @@ public:
      * @param before An action, after which the rest are added.
      */
     void registerMenu(MenuType type, QMenu *menu, bool autoHide = false, QAction *before = nullptr);
-
-    void addWidget(const QString &id);
-    void removeWidget(const QString &id);
-    void updateWidget(const QString &id);
-
     /*!
      * Opens 'Add Files' dialog
      * @param parent Parent widget
@@ -187,9 +182,20 @@ signals:
      * Use it to show player's window and to raise it to the top.
      */
     void showMainWindowCalled();
-
+    /*!
+     * Emitted when some general plugin adds widget.
+     * User interface should create this widget using the given \b id.
+     */
     void widgetAdded(const QString &id);
+    /*!
+     * Emitted when some general plugin removes widget \b id.
+     * User interface should remove widget with the given \b id.
+     */
     void widgetRemoved(const QString &id);
+    /*!
+     * Emitted when some general plugin changes settings of the widget \b id.
+     * User interface should recreate widget with the given \b id.
+     */
     void widgetUpdated(const QString &id);
 
 private slots: