Updated/added some comments on VOC/WAVE functions

svn-id: r21384

3 files changed, 28 insertions, 7 deletions

diff --git a/sound/voc.h b/sound/voc.h
index a62b785e3b..59ddc305ec 100644
--- a/sound/voc.h
+++ b/sound/voc.h
@@ -64,9 +64,21 @@ struct VocBlockHeader {
  */
 extern int getSampleRateFromVOCRate(int vocSR);
 
-//extern byte *loadVOCFromStream(Common::ReadStream &stream, int &size, int &rate, int &loops, int &begin_loop, int &end_loop);
+/**
+ * Try to load a VOC from the given seekable stream. Returns a pointer to memory
+ * containing the PCM sample data (allocated with malloc). It is the callers
+ * responsibility to dellocate that data again later on! Currently this
+ * function only supports uncompressed raw PCM data.
+ */
 extern byte *loadVOCFromStream(Common::ReadStream &stream, int &size, int &rate);
 
+/**
+ * Try to load a VOC from the given seekable stream and create an AudioStream
+ * from that data. Currently this function only supports uncompressed raw PCM
+ * data. Looping is not supported.
+ *
+ * This function uses loadVOCFromStream() internally.
+ */
 AudioStream *makeVOCStream(Common::ReadStream &stream);
 
 #endif
diff --git a/sound/wave.cpp b/sound/wave.cpp
index fdb358a1a9..264e4ae7bb 100644
--- a/sound/wave.cpp
+++ b/sound/wave.cpp
@@ -164,8 +164,6 @@ AudioStream *makeWAVStream(Common::SeekableReadStream &stream) {
 	if (!loadWAVFromStream(stream, size, rate, flags, &type))
 		return 0;
 
-	flags |= Audio::Mixer::FLAG_AUTOFREE;
-
 	if (type == 17) // IMA ADPCM
 		return makeADPCMStream(&stream, size, kADPCMIma, (flags & Audio::Mixer::FLAG_STEREO) ? 2 : 1);
 
@@ -173,5 +171,8 @@ AudioStream *makeWAVStream(Common::SeekableReadStream &stream) {
 	assert(data);
 	stream.read(data, size);
 
+	// Since we allocated our own buffer for the data, we must set the autofree flag.
+	flags |= Audio::Mixer::FLAG_AUTOFREE;
+
 	return makeLinearInputStream(rate, flags, data, size, 0, 0);
 }
diff --git a/sound/wave.h b/sound/wave.h
index cc18852362..f0aca0c9fc 100644
--- a/sound/wave.h
+++ b/sound/wave.h
@@ -30,13 +30,21 @@ class AudioStream;
 namespace Common { class SeekableReadStream; }
 
 /**
- * Try to load a WAVE from the given seekable stream. Returns true if successful; in that case,
- * the stream will point at the start of the audio data, and size, rate and flags contain
- * all information about the data necessary for playback.
- * Currently this only support uncompressed raw PCM data.
+ * Try to load a WAVE from the given seekable stream. Returns true if
+ * successful. In that case, the stream's seek position will be set to the
+ * start of the audio data, and size, rate and flags contain information
+ * necessary for playback. Currently this function only supports uncompressed
+ * raw PCM data as well as IMA ADPCM.
  */
 extern bool loadWAVFromStream(Common::SeekableReadStream &stream, int &size, int &rate, byte &flags, uint16 *wavType = 0, int *blockAlign = 0);
 
+/**
+ * Try to load a WAVE from the given seekable stream and create an AudioStream
+ * from that data. Currently this function only supports uncompressed raw PCM
+ * data as well as IMA ADPCM.
+ *
+ * This function uses loadWAVFromStream() internally.
+ */
 AudioStream *makeWAVStream(Common::SeekableReadStream &stream);
 
 #endif