updated API documentation

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

10 files changed, 107 insertions, 41 deletions

diff --git a/src/qmmp/audioparameters.h b/src/qmmp/audioparameters.h
index 54d96bd41..ac7a6566e 100644
--- a/src/qmmp/audioparameters.h
+++ b/src/qmmp/audioparameters.h
@@ -1,5 +1,5 @@
 /***************************************************************************
- *   Copyright (C) 2009-2016 by Ilya Kotov                                 *
+ *   Copyright (C) 2009-2017 by Ilya Kotov                                 *
  *   forkotov02@ya.ru                                                      *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -32,10 +32,13 @@ class AudioParameters
 {
 public:
 
+    /*!
+     * Byte order of samples.
+     */
     enum ByteOrder
     {
-        LittleEndian = 0,
-        BigEndian
+        LittleEndian = 0, /*!< Samples are in little-endian byte order */
+        BigEndian         /*!< Samples are in big-endian byte order */
     };
     /*!
      * Constructor.
@@ -98,7 +101,9 @@ public:
      * less or equal to the value returned by \b bitsPerSample().
      */
     int validBitsPerSample() const;
-
+    /*!
+     * Returns byte order for selected audio format.
+     */
     ByteOrder byteOrder() const;
     /*!
      * Returns string represention of the audio parameters.
@@ -118,7 +123,12 @@ public:
      * of the given pcm data \b format.
      */
     static int validBitsPerSample(Qmmp::AudioFormat format);
-
+    /*!
+     * Find audio format by number of bits and byte  order.
+     * Returns \b Qmmp::UNKNOWN if format is not found.
+     * @param bits Number of used bits in the sample (precision).
+     * @param byteOrder Byte order.
+     */
     static Qmmp::AudioFormat findAudioFormat(int bits, ByteOrder byteOrder = LittleEndian);
 
 private:
diff --git a/src/qmmp/effect.h b/src/qmmp/effect.h
index 85fc5fdd2..8b0c6374f 100644
--- a/src/qmmp/effect.h
+++ b/src/qmmp/effect.h
@@ -104,7 +104,10 @@ public:
      * @param factory Effect plugin factory.
      */
     static bool isEnabled(EffectFactory* factory);
-
+    /*!
+     * Finds effect factory object by short name \b shortName. Returns effect factory pointer.
+     * If no match is found, 0 is returned. The search is case sensitive.
+     */
     static EffectFactory *findFactory(const QString &shortName);
 
 private:
diff --git a/src/qmmp/soundcore.h b/src/qmmp/soundcore.h
index 819d93313..38ce3adb6 100644
--- a/src/qmmp/soundcore.h
+++ b/src/qmmp/soundcore.h
@@ -93,9 +93,10 @@ public:
      * Returns current bitrate (in kbps)
      */
     int bitrate() const;
-
+    /*!
+     * Returns output audio parameters.
+     */
     AudioParameters audioParameters() const;
-
     /*!
      * Returns the current state.
      */
@@ -195,7 +196,10 @@ signals:
      * @param bitrate New bitrate (in kbps)
      */
     void bitrateChanged(int bitrate);
-
+    /*!
+     * Emitted when audio parameters have changed.
+     * @param p New audio parameters for output.
+     */
     void audioParametersChanged(const AudioParameters &p);
     /*!
      * Emitted when new metadata is available.
diff --git a/src/qmmp/statehandler.h b/src/qmmp/statehandler.h
index ba3de2f9f..8283cf9fc 100644
--- a/src/qmmp/statehandler.h
+++ b/src/qmmp/statehandler.h
@@ -50,9 +50,11 @@ public:
      * @param bitrate Current bitrate (in kbps).
      */
     void dispatch(qint64 elapsed, int bitrate);
-
+    /*!
+     * Sends information about audio parameters.
+     * @param p Output audio patameters.
+     */
     void dispatch(const AudioParameters &p);
-
     /*!
      * Sends information about song length
      * @param length song length in milliseconds
@@ -87,7 +89,9 @@ public:
      * Returns current bitrate (in kbps)
      */
     int bitrate() const;
-
+    /*!
+     * Returns output audio parameters.
+     */
     AudioParameters audioParameters() const;
     /*!
      * Returns the current state.
@@ -117,9 +121,11 @@ signals:
      * @param bitrate New bitrate (in kbps)
      */
     void bitrateChanged(int bitrate);
-
+    /*!
+     * Emitted when audio parameters have changed.
+     * @param p New audio parameters for output.
+     */
     void audioParametersChanged(const AudioParameters &p);
-
      /*!
      * This signal is emitted when the stream reader fills it's buffer.
      * The argument \b progress indicates the current percentage of buffering completed.
diff --git a/src/qmmp/visual.h b/src/qmmp/visual.h
index e69242bf9..88a1c5b86 100644
--- a/src/qmmp/visual.h
+++ b/src/qmmp/visual.h
@@ -95,15 +95,26 @@ public:
     static void showSettings(VisualFactory *factory, QWidget *parent);
     /*!
      * Adds data for visualization.
-     * @param ocm Audio data.
+     * @param pcm Audio data.
      * @param samples Number of samples.
-     * @param chan Number of channels.
+     * @param channels Number of channels.
+     * @param ts Elapsed time (in milliseconds).
+     * @param delay Audio output delay.
      */
     static void addAudio(float *pcm, int samples, int channels, qint64 ts, qint64 delay);
+    /*!
+     * Clears visualization buffer.
+     */
     static void clearBuffer();
 
 public slots:
+    /*!
+     * Starts visualization.
+     */
     virtual void start() = 0;
+    /*!
+     * Stops visualization.
+     */
     virtual void stop() = 0;
 
 signals:
@@ -118,7 +129,13 @@ protected:
      * @param event QCloseEvent insatance.
      */
     virtual void closeEvent (QCloseEvent *event);
-
+    /*!
+     * Takes visualization data. Caller should allocate \b QMMP_VISUAL_NODE_SIZE
+     * bytes for each channel. If buffer for right channel is not specified,
+     * this function will average data from left and right channels.
+     * @param left Left channel buffer.
+     * @param right Right channel buffer.
+     */
     bool takeData(float *left, float *right = 0);
 
 private:
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.
      */