playlist format api documentation

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

10 files changed, 61 insertions, 45 deletions

diff --git a/src/qmmpui/fileloader.h b/src/qmmpui/fileloader.h
index c3031b2f7..e89f4a166 100644
--- a/src/qmmpui/fileloader.h
+++ b/src/qmmpui/fileloader.h
@@ -26,7 +26,8 @@
 
 class PlayListItem;
 
-/*! @brief File loader class.
+/*! @internal
+ * @brief File loader class.
  *
  * This class represents fileloader object that
  * processes file list in separate thread and emits
diff --git a/src/qmmpui/generalhandler.h b/src/qmmpui/generalhandler.h
index 563ff3f09..179c956d8 100644
--- a/src/qmmpui/generalhandler.h
+++ b/src/qmmpui/generalhandler.h
@@ -33,7 +33,7 @@ class Control;
 class GeneralFactory;
 class CommandLineManager;
 
-/*! @brief The GeneralHandler class provied simple api to access general and command line plugins.
+/*! @brief The GeneralHandler class provides simple api to access general and command line plugins.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class GeneralHandler : public QObject
diff --git a/src/qmmpui/mediaplayer.h b/src/qmmpui/mediaplayer.h
index a595b8453..51d56a5f0 100644
--- a/src/qmmpui/mediaplayer.h
+++ b/src/qmmpui/mediaplayer.h
@@ -96,7 +96,6 @@ private:
     static MediaPlayer* m_instance;
     bool m_repeat;
     int m_skips;
-
 };
 
 #endif
diff --git a/src/qmmpui/playlistformat.h b/src/qmmpui/playlistformat.h
index c5135486c..7e5b8c537 100644
--- a/src/qmmpui/playlistformat.h
+++ b/src/qmmpui/playlistformat.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2006-2008 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  *
@@ -22,16 +22,17 @@
 #define _PALYLISTFORMAT_H
 #include <QStringList>
 
-
 class AbstractPlaylistItem;
-/*!
- * Abstract interface for playlist formats.
- *
+
+/*! @brief Abstract interface for playlist formats.
  * @author Vladimir Kuznetsov <vovanec@gmail.com>
  */
 class PlaylistFormat
 {
 public:
+    /*!
+     * Object destructor
+     */
     virtual ~PlaylistFormat()
     {
         ;
@@ -41,25 +42,23 @@ public:
      * ready file pathes to fill the playlist.
      */
     virtual QStringList decode(const QString& contents) = 0;
-
     /*!
      * Takes the list of AbstractPlaylistItem objects, should return string of
      * encoded playlist file
      */
     virtual QString encode(const QList<AbstractPlaylistItem*>& contents) = 0;
-
     /*!
      * Returns list of file extensions that current format supports
      */
     virtual QStringList getExtensions()const = 0;
-
     /*!
      * Verifies is the \b ext file extension supported by current playlist format.
      */
     virtual bool hasFormat(const QString& ext) = 0;
-
-    /// Unique name of playlist format.
-    virtual QString name()const = 0;
+    /*!
+     * Unique name of playlist format.
+     */
+    virtual QString name() const = 0;
 };
 
 Q_DECLARE_INTERFACE(PlaylistFormat,"PlaylistFormatInterface/1.0");
diff --git a/src/qmmpui/playlistitem.h b/src/qmmpui/playlistitem.h
index 85241a70e..dd2898f64 100644
--- a/src/qmmpui/playlistitem.h
+++ b/src/qmmpui/playlistitem.h
@@ -26,7 +26,7 @@
 class FileInfo;
 class QSettings;
 
-/** @brief The QTableWidgetItem class provides an item for use with the PlayListModel class.
+/** @brief The PlayListItem class provides an item for use with the PlayListModel class.
  * @author Ilya Kotov <forkotov02@hotmail.ru>
  */
 class PlayListItem : public AbstractPlaylistItem
diff --git a/src/qmmpui/playlistmodel.h b/src/qmmpui/playlistmodel.h
index 500182ce1..e22334b07 100644
--- a/src/qmmpui/playlistmodel.h
+++ b/src/qmmpui/playlistmodel.h
@@ -72,7 +72,8 @@ struct SimpleSelection
     int m_anchor;
     QList<int>m_selected_rows;
 };
-/*! @brief Helper class used for tags update after details dialog closing.
+/*! @internal
+ * @brief Helper class used for tags update after details dialog closing.
  *
  * @author Vladimir Kuznetsov <vovanec@gmail.com>
  */
@@ -88,7 +89,7 @@ public:
 protected slots:
     void updateTag();
 };
-/*! @brief This class provides a data model for the playlist.
+/*! @brief The PlayListModel class provides a data model for the playlist.
  *
  * @author Vladimir Kuznetsov <vovanec@gmail.com>
  * @author Ilya Kotov <forkotov02@hotmail.ru>
@@ -410,8 +411,8 @@ public slots:
     void setUseMetadata(bool enabled);
     /*!
      * Sets short title format
-     * @param format title format. (Expressions: %p - artist, %a - album, %t - title, %n - track,
-     * %g - genre, %f - file name, %F - full path, %y - year)
+     * @param format title format. (Expressions: "%p" - artist, "%a" - album, "%t" - title, "%n" - track,
+     * "%g" - genre, "%f" - file name, "%F" - full path, "%y" - year)
      */
     void setFormat(const QString &format);
 
diff --git a/src/qmmpui/playlistparser.h b/src/qmmpui/playlistparser.h
index a3ff358e3..7b9688a52 100644
--- a/src/qmmpui/playlistparser.h
+++ b/src/qmmpui/playlistparser.h
@@ -22,24 +22,44 @@
 
 #include <QObject>
 
-
 class PlaylistFormat;
 
-/**
-	@author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @brief The PlaylistParser class provides a simple api to access playlist format plugins.
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class PlaylistParser  : public QObject
 {
-Q_OBJECT
+    Q_OBJECT
 public:
+    /*!
+    * Object constructor,
+    * @param parent Parent object
+    */
     PlaylistParser(QObject *parent);
-
+    /*!
+     * Destructor
+     */
     ~PlaylistParser();
-
+    /*!
+     * Returns a list of supported file extensions.
+     */
     QStringList getExtensions();
+    /*!
+     * Returns \b true if file \b filePath is supported, otherwise \b false
+     */
     bool supports(const QString &filePath);
+    /*!
+     * Returns a list of the installed playlist formats.
+     */
     QList<PlaylistFormat*> formats();
+    /*!
+     * Returns a pointer to the object's instance.
+     */
     static PlaylistParser* instance();
+    /*!
+     * Finds playlist format by file path \b filePath
+     * Returns \b 0 if file \b filePath is unsupported.
+     */
     PlaylistFormat *findByPath(const QString &filePath);
 
 private:
diff --git a/src/qmmpui/playlistsettings.h b/src/qmmpui/playlistsettings.h
index 5efc81393..cce4f35e1 100644
--- a/src/qmmpui/playlistsettings.h
+++ b/src/qmmpui/playlistsettings.h
@@ -22,9 +22,9 @@
 
 #include <QString>
 
-/**
-    @author Ilya Kotov <forkotov02@hotmail.ru>
-*/
+/*! @internal
+ * @author Ilya Kotov <forkotov02@hotmail.ru>
+ */
 class PlaylistSettings
 {
 public:
diff --git a/src/qmmpui/playstate.h b/src/qmmpui/playstate.h
index e4af7fa6f..a2b525f7d 100644
--- a/src/qmmpui/playstate.h
+++ b/src/qmmpui/playstate.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2006 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  *
@@ -21,14 +21,11 @@
 #ifndef _PLAYSTATE_H
 #define _PLAYSTATE_H
 
-/**
-   @author Vladimir Kuznetsov <vovanec@gmail.com>
- */
-
 #include <playlistmodel.h>
 
-/*!
- * Abstract class that represents data model playing states
+/*! @internal
+ * @brief Abstract class that represents data model playing states.
+ * @author Vladimir Kuznetsov <vovanec@gmail.com>
  */
 class PlayState
 {
@@ -50,7 +47,6 @@ public:
     {
         ;
     };
-
     /*!
      * Service method, can be used for state initializing.
      */
@@ -72,9 +68,9 @@ protected:
     PlayListModel* m_model;
 };
 
-/*!
- *  Represents normal playing state.
- *  @author Vladimir Kuznetsov <vovanec@gmail.com>
+/*! @internal
+ * @brief Represents normal playing state.
+ * @author Vladimir Kuznetsov <vovanec@gmail.com>
  */
 class NormalPlayState : public PlayState
 {
@@ -84,9 +80,9 @@ public:
     NormalPlayState(PlayListModel* model);
 };
 
-/*!
- *  Represents shuffle playing state.
- *  @author Vladimir Kuznetsov <vovanec@gmail.com>
+/*! @internal
+ * @brief Represents shuffle playing state.
+ * @author Vladimir Kuznetsov <vovanec@gmail.com>
  */
 class ShufflePlayState : public PlayState
 {
diff --git a/src/qmmpui/qtfiledialog.h b/src/qmmpui/qtfiledialog.h
index 3e4598bf5..1cff174c9 100644
--- a/src/qmmpui/qtfiledialog.h
+++ b/src/qmmpui/qtfiledialog.h
@@ -26,8 +26,8 @@
 
 class QTranslator;
 
-/**
-   @author Vladimir Kuznetsov <vovanec@gmail.com>
+/*! @internal
+ * @author Vladimir Kuznetsov <vovanec@gmail.com>
  */
 
 class QtFileDialogFactory : public QObject, public FileDialogFactory