From 19f3591de1f8a6ec7547ab950d1488cf5fb382e6 Mon Sep 17 00:00:00 2001
From: "Uwe L. Korn" <uwelk@xhochy.com>
Date: Tue, 10 Jun 2014 16:02:04 +0100
Subject: [PATCH] Add some more documentation

---
 src/libtomahawk/audio/AudioEngine.h | 38 ++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/src/libtomahawk/audio/AudioEngine.h b/src/libtomahawk/audio/AudioEngine.h
index 9432454c1..55b8cf9fe 100644
--- a/src/libtomahawk/audio/AudioEngine.h
+++ b/src/libtomahawk/audio/AudioEngine.h
@@ -43,8 +43,25 @@ public:
     explicit AudioEngine();
     ~AudioEngine();
 
+    /**
+     * List the MIME types we can play.
+     *
+     * This list might not include all possible MIME types that can be played.
+     * If you know that a certain service always returns a specific MIME type
+     * not reported here, we still might be able to play this media. Please
+     * check the individual backends why they do not report it and if every
+     * (recent) version supports this type.
+     *
+     * @return A list of playable MIME types.
+     */
     QStringList supportedMimeTypes() const;
-    unsigned int volume() const; // in percent
+
+    /**
+     * Reports the current set volume in percent (0-100).
+     *
+     * @return Current volume in percent.
+     */
+    unsigned int volume() const;
 
     AudioState state() const;
     bool isPlaying() const;
@@ -69,7 +86,26 @@ public:
     Tomahawk::result_ptr currentTrack() const;
     Tomahawk::query_ptr stopAfterTrack() const;
 
+    /**
+     * Get the current position in the media.
+     *
+     * As the user might seek forwards and backwards this only returns the
+     * location in the media, not the actual time that the media was already
+     * playing.
+     * @return The current time in milliseconds.
+     */
     qint64 currentTime() const;
+
+    /**
+     * Returns the total duration of the currently playing track.
+     *
+     * For some media this time might only be an estimate as metadate might
+     * not have reported a duration and thus the duration is estimated. During
+     * playback we might get a better estimate so that the return value may
+     * differ between multiple calls.
+     *
+     * @return The total duration in milliseconds.
+     */
     qint64 currentTrackTotalTime() const;
 
     int equalizerBandCount();