updated api documentation

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

15 files changed, 136 insertions, 28 deletions

diff --git a/src/qmmp/abstractengine.h b/src/qmmp/abstractengine.h
index 603bc078a..c935aa0b3 100644
--- a/src/qmmp/abstractengine.h
+++ b/src/qmmp/abstractengine.h
@@ -92,7 +92,7 @@ public:
      */
     static QList<EngineFactory*> enabledFactories();
     /*!
-     * Returns EngineFactory pointer which supports file \b path or 0 if file \b path is unsupported
+     * Returns EngineFactory pointer which supports file \b path or 0 if file \b path is unsupported.
      */
     static EngineFactory *findByFilePath(const QString &path);
     /*!
@@ -103,9 +103,14 @@ public:
     static void setEnabled(EngineFactory *factory, bool enable = true);
     /*!
      * Returns \b true if engine is enabled, otherwise returns \b false
+     * This function uses \b QObject::objectName() function.
      * @param factory Engine plugin factory.
      */
     static bool isEnabled(EngineFactory *factory);
+    /*!
+     * Returns \b true if engine is enabled, otherwise returns \b false
+     * @param engine Engine object.
+     */
     static bool isEnabled(AbstractEngine *engine);
     /*!
      * Returns plugin file path.
diff --git a/src/qmmp/buffer.h b/src/qmmp/buffer.h
index f9fe83f10..58c5f0f2c 100644
--- a/src/qmmp/buffer.h
+++ b/src/qmmp/buffer.h
@@ -43,11 +43,11 @@ public:
         size = 0;
     }
 
-    float *data;         /*!< Audio data */
-    size_t samples;      /*!< Audio data size in samples */
-    size_t size;         /*!< Buffer size in samples */
-    unsigned int rate;   /*!< Buffer bitrate */
-    QSharedPointer<TrackInfo> trackInfo;
+    float *data;                         /*!< Audio data. */
+    size_t samples;                      /*!< Audio data size in samples. */
+    size_t size;                         /*!< Buffer size in samples. */
+    unsigned int rate;                   /*!< Buffer bitrate. */
+    QSharedPointer<TrackInfo> trackInfo; /*!< Attached track information. */
 };
 
 
diff --git a/src/qmmp/decoder.h b/src/qmmp/decoder.h
index c1327c77e..254e0d204 100644
--- a/src/qmmp/decoder.h
+++ b/src/qmmp/decoder.h
@@ -102,11 +102,23 @@ public:
     bool hasMetaData() const;
     /*!
      * Takes metadata out of decoder and returns it.
-     * Attention: hasMetaData() should return \b true before use of this fuction.
+     * Attention: hasMetaData() should return \b true before using of this fuction.
      */
     QMap<Qmmp::MetaData, QString> takeMetaData();
+    /*!
+     * Sets extra track property.
+     * \param key Property key.
+     * \param value Property value.
+     */
     void setProperty(Qmmp::TrackProperty key, const QVariant &value);
+    /*!
+     * Updates all extra track properties.
+     * \param properties New track properties.
+     */
     void setProperties(const QMap<Qmmp::TrackProperty, QString> &properties);
+    /*!
+     * Returns track properties
+     */
     const QMap<Qmmp::TrackProperty, QString> &properties() const;
     /*!
      * Returns DecoderFactory pointer which supports file \b path or 0 if file \b path is unsupported
diff --git a/src/qmmp/decoderfactory.h b/src/qmmp/decoderfactory.h
index 2c12ec283..3eec5b9ad 100644
--- a/src/qmmp/decoderfactory.h
+++ b/src/qmmp/decoderfactory.h
@@ -86,14 +86,15 @@ public:
      * Extracts metadata and audio information from file \b path and returns a list of \b TrackInfo items.
      * One file may contain several playlist items (for example: cda disk or flac with embedded cue)
      * @param fileName File path.
-     * @param parts parts of metadata which should be extracted from file
+     * @param parts parts of metadata which should be extracted from file.
      * @param ignoredPaths Pointer to a list of the files which should be ignored by the recursive search
-     * (useful to exclude cue data files from playlist)
+     * (useful to exclude cue data files from playlist).
      */
     virtual QList<TrackInfo *> createPlayList(const QString &fileName, TrackInfo::Parts parts, QStringList *ignoredPaths) = 0;
     /*!
      * Creats metadata object, which provides full access to file tags.
      * @param path File path.
+     * @param readOnly Open file in read-only mode (\b true - enabled, \b false - disable).
      * @return MetaDataModel pointer.
      */
     virtual MetaDataModel* createMetaDataModel(const QString &path, bool readOnly) = 0;
diff --git a/src/qmmp/enginefactory.h b/src/qmmp/enginefactory.h
index 7701fbce5..32c9a0237 100644
--- a/src/qmmp/enginefactory.h
+++ b/src/qmmp/enginefactory.h
@@ -81,15 +81,17 @@ public:
     virtual AbstractEngine *create(QObject *parent = 0) = 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)
+     * One file may contain several playlist items (for example: cda disk or flac with embedded cue).
      * @param fileName File path.
-     * @param ignoredPaths Pointer to a list of the files which should be ignored by the recursive search
-     * (useful to exclude cue data files from playlist)
+     * @param ignoredPaths Pointer to a list of the files which should be ignored by the recursive search.
+     * @param parts parts of metadata which should be extracted from file.
+     * (useful to exclude cue data files from playlist).
      */
     virtual QList<TrackInfo *> createPlayList(const QString &fileName, TrackInfo::Parts parts, QStringList *ignoredPaths) = 0;
     /*!
      * Creats metadata object, which provides full access to file tags.
      * @param path File path.
+     * @param readOnly Open file in read-only mode (\b true - enabled, \b false - disable).
      * @return MetaDataModel pointer.
      */
     virtual MetaDataModel* createMetaDataModel(const QString &path, bool readOnly) = 0;
diff --git a/src/qmmp/inputsource.h b/src/qmmp/inputsource.h
index a5864a41e..eb9e1f6a8 100644
--- a/src/qmmp/inputsource.h
+++ b/src/qmmp/inputsource.h
@@ -41,7 +41,7 @@ Q_OBJECT
 public:
     /*!
      * Object contsructor.
-     * @param url Input source path or url.
+     * @param path Input source path or url.
      * @param parent Parent object.
      */
     InputSource(const QString &path, QObject *parent = 0);
@@ -113,7 +113,7 @@ public:
     QHash<QString, QString> takeStreamInfo();
     /*!
      * Creates InputSource object.
-     * @param url Input source path or url.
+     * @param path Input source path or url.
      * @param parent Parent object.
      * Returns \b 0 if the given url is not supported.
      */
diff --git a/src/qmmp/metadatamanager.h b/src/qmmp/metadatamanager.h
index 956ed1de9..171dcbcd6 100644
--- a/src/qmmp/metadatamanager.h
+++ b/src/qmmp/metadatamanager.h
@@ -53,6 +53,7 @@ public:
      * 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 Local file path or URL.
+     * @param parts parts of metadata which should be extracted from file.
      * @param ignoredPaths Pointer to a list of the files which should be ignored by the recursive search
      * (useful to exclude cue data files from playlist)
      */
@@ -60,6 +61,7 @@ public:
     /*!
      * Creats metadata object, which provides full access to file tags.
      * @param url File path or URL.
+     * @param readOnly Open file in read-only mode (\b true - enabled, \b false - disable).
      * @return MetaDataModel pointer or null pointer.
      */
     MetaDataModel* createMetaDataModel(const QString &url, bool readOnly) const;
diff --git a/src/qmmp/metadatamodel.h b/src/qmmp/metadatamodel.h
index e9d409c30..a9163410f 100644
--- a/src/qmmp/metadatamodel.h
+++ b/src/qmmp/metadatamodel.h
@@ -31,16 +31,42 @@
 #include "tagmodel.h"
 
 
+/*! @brief Container of extra file/track property.
+ * @author Ilya Kotov <forkotov02@ya.ru>
+ */
 class QMMP_EXPORT MetaDataItem
 {
 public:
+    /*!
+     * Constructor
+     * \param name Localized name of property.
+     * \param value Property value.
+     * \param suffix Localized suffix of property (i.e. kB, kB/s, etc).
+     */
     MetaDataItem(const QString &name, const QVariant &value, const QString &suffix = QString());
-
+    /*!
+     * Returns localized name of property.
+     */
     const QString &name() const;
+    /*!
+     * Changes localized name to \b name
+     */
     void setName(const QString &name);
+    /*!
+     * Returns property value.
+     */
     const QVariant &value() const;
+    /*!
+     * Returns value of property.
+     */
     void setValue(const QString &value);
+    /*!
+     * Returns suffix of property.
+     */
     const QString &suffix() const;
+    /*!
+     * Changes property suffix to \b suffixed
+     */
     void setSuffix(const QString &suffix);
 
 private:
@@ -54,23 +80,35 @@ private:
 class QMMP_EXPORT MetaDataModel
 {
 public:
+    /*!
+     * Details dialog settings.
+     */
     enum DialogHint
     {
-        NO_HINTS = 0x0,
-        IS_COVER_EDITABLE = 0x1,
-        COMPLETE_PROPERTY_LIST = 0x2
+        NO_HINTS = 0x0,               /*!< Default value. */
+        IS_COVER_EDITABLE = 0x1,      /*!< Enable cover editor. */
+        COMPLETE_PROPERTY_LIST = 0x2  /*!< Show properties from \b extraProperties() only (ignore other sources) */
     };
     Q_DECLARE_FLAGS(DialogHints, DialogHint)
     /*!
      * Constructor.
+     * @param readOnly Open file in read-only mode (\b true - enabled, \b false - disable).
+     * @param hints Details dialog settings.
      */
     MetaDataModel(bool readOnly, DialogHints hints = NO_HINTS);
     /*!
      * Destructor.
      */
     virtual ~MetaDataModel();
-
+    /*!
+     * Returns extra properties of the media source (in addition to the \b Qmmp::TrackProperty values).
+     * Default implemetation returns empty array.
+     */
     virtual QList<MetaDataItem> extraProperties() const;
+    /*!
+     * Returns a list of long descriptions.
+     * Default implemetation returns empty array.
+     */
     virtual QList<MetaDataItem> descriptions() const;
     /*!
      * Returns a list of available tags.
@@ -82,17 +120,39 @@ public:
      * Subclass should reimplement this function. Default implementation returns empty pixmap.
      */
     virtual QPixmap cover() const;
+    /*!
+     * Sets cover.
+     * @param pix Cover pixmap.
+     * Subclass should reimplement this function. Default implementation does nothing.
+     */
     virtual void setCover(const QPixmap &pix);
+    /*!
+     * Removes cover.
+     * Subclass should reimplement this function. Default implementation does nothing.
+     */
     virtual void removeCover();
     /*!
      * Returns path to cover pixmap.
      */
     virtual QString coverPath() const;
+    /*!
+     * Returns \b true if file is opened in read only mode. Otherwise returns \b false.
+     */
     bool isReadOnly() const;
+    /*!
+     * Returns details dialog hints.
+     */
     const DialogHints &dialogHints() const;
 
 protected:
+    /*!
+     * Changes details dialog hints to \b hints
+     */
     void setDialogHints(const DialogHints &hints);
+    /*!
+     * Enables/Disables read only mode (\b true - enabled, \b false - disable).
+     * @param readOnly read only mode (\b true - enabled, \b false - disable).
+     */
     void setReadOnly(bool readOnly);
 
 private:
diff --git a/src/qmmp/output.h b/src/qmmp/output.h
index 8ab26b235..8a2b359ce 100644
--- a/src/qmmp/output.h
+++ b/src/qmmp/output.h
@@ -76,7 +76,11 @@ public:
      * Resumes processing audio data.
      */
     virtual void resume();
-
+    /*!
+     * Sets track information for output.
+     * Default implementation does nothing.
+     * Reimplement this function to receive metadata.
+     */
     virtual void setTrackInfo(const TrackInfo &info);
     /*!
      * Returns selected audio parameters.
diff --git a/src/qmmp/qmmp.cpp b/src/qmmp/qmmp.cpp
index 5c7b659dc..5b0cabbf5 100644
--- a/src/qmmp/qmmp.cpp
+++ b/src/qmmp/qmmp.cpp
@@ -102,7 +102,7 @@ QStringList Qmmp::findPlugins(const QString &prefix)
 {
     QDir pluginDir(pluginPath() + "/" + prefix);
     QStringList paths;
-    foreach (QFileInfo info,  pluginDir.entryInfoList(QStringList() << "*.dll" << "*.so", QDir::Files))
+    foreach (QFileInfo info, pluginDir.entryInfoList(QStringList() << "*.dll" << "*.so", QDir::Files))
         paths << info.canonicalFilePath();
     return paths;
 }
diff --git a/src/qmmp/qmmp.h b/src/qmmp/qmmp.h
index 2f22a1327..9567ee457 100644
--- a/src/qmmp/qmmp.h
+++ b/src/qmmp/qmmp.h
@@ -159,8 +159,11 @@ public:
      * Returns the location of the installed Qmmp plugins.
      */
     static QString pluginPath();
+    /*!
+     * Returns a list of found Qmmp plugins (full paths).
+     * @param prefix Plugin type or directory name (examples: Inpunt, Transport, Output).
+     */
     static QStringList findPlugins(const QString &prefix);
-
     /*!
      * Returns system language if uiLanguageID() is 'auto'. Otherwise returns uiLanguageID().
      */
diff --git a/src/qmmp/soundcore.h b/src/qmmp/soundcore.h
index 75fbf9543..d5875cf88 100644
--- a/src/qmmp/soundcore.h
+++ b/src/qmmp/soundcore.h
@@ -114,6 +114,9 @@ public:
      * Returns a hash of stream information if available
      */
     QHash<QString, QString> streamInfo() const;
+    /*!
+     * Returns current track information.
+     */
     const TrackInfo &trackInfo() const;
     /*!
      *  Indicates that the current active engine will be used for the next queued track.
@@ -207,6 +210,9 @@ signals:
      * Emitted when new stream information is available.
      */
     void streamInfoChanged();
+    /*!
+     * Emitted when new track information is available.
+     */
     void trackInfoChanged();
     /*!
      * This signal is emitted when the state of the SoundCore has changed.
diff --git a/src/qmmp/statehandler.h b/src/qmmp/statehandler.h
index 790ee1195..40fbb974f 100644
--- a/src/qmmp/statehandler.h
+++ b/src/qmmp/statehandler.h
@@ -60,7 +60,10 @@ public:
      * @param duration track length in milliseconds
      */
     void dispatch(qint64 duration);
-
+    /*!
+     * Sends track information.
+     * @param info track information.
+     */
     bool dispatch(const TrackInfo &info);
     /*!
      * Sends stream information \b info
diff --git a/src/qmmpui/metadataformatter.h b/src/qmmpui/metadataformatter.h
index 1a582b91c..2645e3fe7 100644
--- a/src/qmmpui/metadataformatter.h
+++ b/src/qmmpui/metadataformatter.h
@@ -78,12 +78,16 @@ public:
      */
     QString format(const PlayListTrack *item) const;
     /*!
-     * Converts metadata of \b TrackInfo pointer \b info to one string using template.
+     * Converts metadata of \b TrackInfo reference \b info to one string using template.
      * \param info pointer to \b TrackInfo object.
-     * \param track Index of track.
+     * \param trackIndex Index of track.
      */
     QString format(const TrackInfo &info, int trackIndex = 0) const;
-
+    /*!
+     * Converts metadata of \b TrackInfo pointer \b info to one string using template.
+     * \param info pointer to \b TrackInfo object.
+     * \param trackIndex Index of track.
+     */
     QString format(const TrackInfo *info, int trackIndex = 0) const;
     /*!
      * Returns formatted duration (example: 05:02:03).
@@ -91,6 +95,7 @@ public:
      * \param hideZero Setting for zero values output.
      * If \b hideZero is \b true, then the function outputs empty string for zero length,
      * otherwise outputs "0:00".
+     * \param showMs Adds milliseconds to the end of output (example: 05:02:03.324).
      */
     static QString formatDuration(qint64 duration, bool hideZero = true, bool showMs = false);
 
diff --git a/src/qmmpui/uihelper.h b/src/qmmpui/uihelper.h
index 46844e788..2ba17cc27 100644
--- a/src/qmmpui/uihelper.h
+++ b/src/qmmpui/uihelper.h
@@ -61,7 +61,7 @@ public:
     {
         TOOLS_MENU = 0, /*!< tools menu */
         PLAYLIST_MENU,  /*!< playlist context menu */
-        ADD_MENU
+        ADD_MENU        /*!< "add"/"file" menu */
     };
     /*!
      * Returns \b true if one of the general plugin can change visibility, otherwise returns \b false
@@ -89,8 +89,13 @@ public:
      * @param parent Parent widget
      */
     QMenu *createMenu(MenuType type, const QString &title = QString(), QWidget *parent = 0);
+    /*!
+     * Registers existing menu for access from general plugins.
+     * @param type Menu type.
+     * @param menu Menu pointer.
+     * @param before An action, after which the rest are added.
+     */
     void registerMenu(MenuType type, QMenu *menu, QAction *before = 0);
-
     /*!
      * Opens 'Add Files' dialog
      * @param parent Parent widget