From 2cf79ca6cff6ae9e198c6ea25a22fb63a7e06349 Mon Sep 17 00:00:00 2001
From: janwas <jan@wildfiregames.com>
Date: Sat, 30 Oct 2004 15:17:19 +0000
Subject: [PATCH] more dox :]

This was SVN commit r1279.
---
 source/lib/res/snd.cpp |  7 ++++++-
 source/lib/res/snd.h   | 15 ++++++++++++++-
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/source/lib/res/snd.cpp b/source/lib/res/snd.cpp
index b59be90b5c..b2a0e75eef 100755
--- a/source/lib/res/snd.cpp
+++ b/source/lib/res/snd.cpp
@@ -1507,7 +1507,8 @@ int snd_play(Handle hs, float static_pri)
 // change 3d position of the sound source.
 // if relative (default false), (x,y,z) is treated as relative to the
 // listener; otherwise, it is the position in world coordinates.
-// may be called at any time.
+// may be called at any time; fails with invalid handle return if
+// the sound has already been closed (e.g. it never played).
 int snd_set_pos(Handle hvs, float x, float y, float z, bool relative)
 {
 	H_DEREF(hvs, VSrc, vs);
@@ -1522,6 +1523,8 @@ int snd_set_pos(Handle hvs, float x, float y, float z, bool relative)
 
 // change gain (amplitude modifier) of the sound source.
 // must be non-negative; 1 -> unattenuated, 0.5 -> -6 dB, 0 -> silence.
+// may be called at any time; fails with invalid handle return if
+// the sound has already been closed (e.g. it never played).
 int snd_set_gain(Handle hvs, float gain)
 {
 	H_DEREF(hvs, VSrc, vs);
@@ -1535,6 +1538,8 @@ int snd_set_gain(Handle hvs, float gain)
 
 // enable/disable looping on the sound source.
 // used to implement variable-length sounds (e.g. while building).
+// may be called at any time; fails with invalid handle return if
+// the sound has already been closed (e.g. it never played).
 //
 // notes:
 // - looping sounds are not discarded if they cannot be played for lack of
diff --git a/source/lib/res/snd.h b/source/lib/res/snd.h
index a7bfa04ac9..dd93118144 100755
--- a/source/lib/res/snd.h
+++ b/source/lib/res/snd.h
@@ -19,6 +19,14 @@
 #include "handle.h"
 
 
+// introduction:
+// this module initializes the sound hardware and provides an interface
+// (backed by the resource manager) that allows any number of sounds
+// to be emitted simultaneously; they are also closed automatically.
+// the most "important" sounds are actually played, while the others
+// are discarded (necessary due to limited number of hardware voices).
+
+
 //
 // device enumeration
 //
@@ -107,15 +115,20 @@ extern int snd_play(Handle hs, float priority = 0.0f);
 // change 3d position of the sound source.
 // if relative (default false), (x,y,z) is treated as relative to the
 // listener; otherwise, it is the position in world coordinates.
-// may be called at any time.
+// may be called at any time; fails with invalid handle return if
+// the sound has already been closed (e.g. it never played).
 extern int snd_set_pos(Handle hs, float x, float y, float z, bool relative = false);
 
 // change gain (amplitude modifier) of the sound source.
 // must be non-negative; 1 -> unattenuated, 0.5 -> -6 dB, 0 -> silence.
+// may be called at any time; fails with invalid handle return if
+// the sound has already been closed (e.g. it never played).
 extern int snd_set_gain(Handle hs, float gain);
 
 // enable/disable looping on the sound source.
 // used to implement variable-length sounds (e.g. while building).
+// may be called at any time; fails with invalid handle return if
+// the sound has already been closed (e.g. it never played).
 //
 // notes:
 // - looping sounds are not discarded if they cannot be played for lack of