updated API documentation

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

5 files changed, 50 insertions, 24 deletions

diff --git a/src/qmmpui/commandlinemanager.h b/src/qmmpui/commandlinemanager.h
index 647e5a2e6..974c064fa 100644
--- a/src/qmmpui/commandlinemanager.h
+++ b/src/qmmpui/commandlinemanager.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2008-2012 by Ilya Kotov                                 *
+ *   Copyright (C) 2008-2017 by Ilya Kotov                                 *
  *   forkotov02@ya.ru                                                      *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -25,28 +25,31 @@
 #include "commandlineoption.h"
 
 
-/*! @brief Helper class used for handle command line plugins
+/*! @brief Helper class used for handle command line plugins.
  * @author Ilya Kotov <forkotov02@ya.ru>
  */
 class CommandLineManager
 {
 public:
     /*!
-     * Executes command \b opt_str
-     * @param opt_str Command line option string
-     * @param args Command arguments
-     * @return Command output result
+     * Executes command \b opt_str.
+     * @param opt_str Command line option string.
+     * @param args Command arguments.
+     * @return Command output result.
      */
     static QString executeCommand(const QString& opt_str, const QStringList &args = QStringList());
     /*!
-     * Return \b true if command \b opt_str is supported, otherwise returns \b false
+     * Return \b true if command \b opt_str is supported, otherwise returns \b false.
      */
     static bool hasOption(const QString &opt_str);
     /*!
-     * Prints usage to stdout
+     * Prints usage to stdout.
      */
     static void printUsage();
-
+    /*!
+     * Prepares help string for output.
+     * @param line Specially formatted help string. Example: "--command||description".
+     */
     static QString formatHelpString(const QString &line);
 
 private:
diff --git a/src/qmmpui/playlistformat.h b/src/qmmpui/playlistformat.h
index aee5c2e8f..4cb7b4d70 100644
--- a/src/qmmpui/playlistformat.h
+++ b/src/qmmpui/playlistformat.h
@@ -58,6 +58,7 @@ public:
      * Takes the list of \b PlayListTrack objects, should return content of
      * encoded playlist file.
      * @param path Playlist file path (May be used to adjust playlist content).
+     * @param contents A list of \b PlayListTrack pointers.
      */
     virtual QByteArray encode(const QList<PlayListTrack*> &contents, const QString &path) = 0;
 };
diff --git a/src/qmmpui/playlistmodel.h b/src/qmmpui/playlistmodel.h
index a58df81b6..c48a20660 100644
--- a/src/qmmpui/playlistmodel.h
+++ b/src/qmmpui/playlistmodel.h
@@ -214,8 +214,11 @@ public:
      * @param selected Selection state (\b true - select, \b false - unselect).
      */
     void setSelected(int first, int last, bool selected = true);
-
-
+    /*!
+     * Sets the selected state of the items with \b indexes to \b select
+     * @param indexes List of item \b indexes.
+     * @param selected Selection state (\b true - select, \b false - unselect)
+     */
     void setSelected(QList<int> indexes, bool selected = true);
     /*!
      * Advances to the next item. Returns \b false if next iten doesn't exist,
@@ -290,7 +293,11 @@ public:
      * Loads playlist with \b f_name name.
      */
     void loadPlaylist(const QString& f_name);
-
+    /*!
+     * Loads playlist from content.
+     * @param fmt Playlist format (short name).
+     * @param data Content of the playlist file.
+     */
     void loadPlaylist(const QString &fmt, const QByteArray &data);
     /*!
      * Saves current songs to the playlist with \b f_name name.
@@ -329,10 +336,13 @@ public:
     int indexOfTrack(int index) const;
     /*!
      * Finds track with index \b track_index.
-     * Return null pointer if playlist does not contain track with index \b track_index.
+     * Returns null pointer if playlist does not contain track with index \b track_index.
      */
     PlayListTrack *findTrack(int track_index) const;
-
+    /*!
+     * Finds tracks by string \b str. The search is case insensitive.
+     * Returns a list of \b PlayListItem pointers.
+     */
     QList<PlayListItem *> findTracks(const QString &str) const;
     /*!
      * Enum of the playlist update flags.
@@ -367,7 +377,9 @@ signals:
      * Emitted when playlist loader thread has finished.
      */
     void loaderFinished();
-
+    /*!
+     * Tells playlist widget to show item at index \b index.
+     */
     void scrollToRequest(int index);
     /*!
      * Emitted when sorting by column is finished.
@@ -476,6 +488,9 @@ public slots:
      * Ensures that the current track is visible.
      */
     void doCurrentVisibleRequest();
+    /*!
+     * Ensures that the playlist item at \b index is visible.
+     */
     void scrollTo(int index);
     /*!
      * Randomly changes items order.
diff --git a/src/qmmpui/playlistparser.cpp b/src/qmmpui/playlistparser.cpp
index 81b4b659e..c6cf7a189 100644
--- a/src/qmmpui/playlistparser.cpp
+++ b/src/qmmpui/playlistparser.cpp
@@ -147,12 +147,12 @@ QList<PlayListTrack *> PlayListParser::loadPlaylist(const QString &f_name)
     return tracks;
 }
 
-QList<PlayListTrack *> PlayListParser::loadPlaylist(const QString &fmt, const QByteArray &contents)
+QList<PlayListTrack *> PlayListParser::loadPlaylist(const QString &fmt, const QByteArray &content)
 {
     foreach (PlayListFormat *p, *m_formats)
     {
         if(p->properties().shortName == fmt)
-            return p->decode(contents);
+            return p->decode(content);
     }
     return QList<PlayListTrack *>();
 }
diff --git a/src/qmmpui/playlistparser.h b/src/qmmpui/playlistparser.h
index 5b0c4d552..35545e2c0 100644
--- a/src/qmmpui/playlistparser.h
+++ b/src/qmmpui/playlistparser.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2008-2013 by Ilya Kotov                                 *
+ *   Copyright (C) 2008-2017 by Ilya Kotov                                 *
  *   forkotov02@ya.ru                                                      *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -39,9 +39,11 @@ public:
      * Returns a list of the supported files name filters, i.e. "*.m3u *.pls"
      */
     static QStringList nameFilters();
-
+    /*!
+     * Returns \b true if file \b url is playlist. Otherwise returns \b false.
+     * \param url Local file path or URL.
+     */
     static bool isPlayList(const QString &url);
-
     /*!
      * Returns PlayListFormat pointer which supports mime type \b mime
      * or \b 0 if mime type \b mime is unsupported
@@ -64,13 +66,18 @@ public:
      */
     static void savePlayList(QList<PlayListTrack *> tracks, const QString &f_name);
     /*!
-     * Loads playlist from file \b f_name
+     * Loads playlist from file \b f_name.
      * @param f_name File name.
-     * @return A list of URLs or file paths.
+     * @return A list of tracks.
      */
     static QList<PlayListTrack *> loadPlaylist(const QString &f_name);
-
-    static QList<PlayListTrack *> loadPlaylist(const QString &fmt, const QByteArray &contents);
+    /*!
+     * Loads playlist from content \b content.
+     * @param fmt Playlist format (short name).
+     * @param content Playlist content.
+     * @return A list of tracks.
+     */
+    static QList<PlayListTrack *> loadPlaylist(const QString &fmt, const QByteArray &content);
     /*!
      * Loads all playlist plugins. Should be called before usage from another thread.
      */