Explain the (admittedly strange) usage of some of our makeXXXStream factory functions

svn-id: r21040

3 files changed, 18 insertions, 0 deletions

diff --git a/sound/flac.h b/sound/flac.h
index d6b9047fa5..fa2eaa077f 100644
--- a/sound/flac.h
+++ b/sound/flac.h
@@ -36,6 +36,12 @@ namespace Common {
 
 DigitalTrackInfo *getFlacTrack(int track);
 
+/**
+ * Create a new AudioStream from the FLAC data in the given
+ * file. If you only want to play part of that file, then seek
+ * to the start position in file before passing it to this
+ * factory function, and specify the appropriate size.
+ */
 AudioStream *makeFlacStream(Common::File *file, uint32 size);
 
 #endif // #ifdef USE_FLAC
diff --git a/sound/mp3.h b/sound/mp3.h
index 3ff5576330..db4f0cec6d 100644
--- a/sound/mp3.h
+++ b/sound/mp3.h
@@ -36,6 +36,12 @@ namespace Common {
 
 DigitalTrackInfo *getMP3Track(int track);
 
+/**
+ * Create a new AudioStream from the MP3 data in the given
+ * file. If you only want to play part of that file, then seek
+ * to the start position in file before passing it to this
+ * factory function, and specify the appropriate size.
+ */
 AudioStream *makeMP3Stream(Common::File *file, uint32 size);
 
 #endif
diff --git a/sound/vorbis.h b/sound/vorbis.h
index 0e7b715927..ee8943cdde 100644
--- a/sound/vorbis.h
+++ b/sound/vorbis.h
@@ -36,6 +36,12 @@ namespace Common {
 
 DigitalTrackInfo *getVorbisTrack(int track);
 
+/**
+ * Create a new AudioStream from the Vorbis data in the given
+ * file. If you only want to play part of that file, then seek
+ * to the start position in file before passing it to this
+ * factory function, and specify the appropriate size.
+ */
 AudioStream *makeVorbisStream(Common::File *file, uint32 size);
 
 #endif