Add some more descriptive comments

simgear/sound/sound.hxx

@@ -44,6 +44,10 @@ static const double MAX_TRANSIT_TIME = 0.1;	// 100 ms.
 /**
  * Class for handling one sound event.
  *
+ * This class handles everything for a particular sound event, by
+ * scanning an a pre-loaded property tree structure for sound
+ * settings, setting up its internal states, and managing sound
+ * playback whenever such an event happens.
  */
 class SGSound
 {
@@ -53,10 +57,58 @@ public:
   SGSound();
   virtual ~SGSound();
 
+  /**
+   * Initialize the sound event.
+   *
+   * Prior to initialization of the sound event the propgrams property root
+   * has to be defined, the sound configuration XML tree has to be loaded 
+   * and a sound manager class has to be defined.
+   *
+   * A sound configuration file would look like this:
+   *  <fx>
+   *   <event_name>
+   *    <name/> Define the name of the event. For refference only.
+   *    <mode/> Either:
+   *              looped: play this sound looped.
+   *              in-transit: play looped while the event is happening.
+   *              once: play this sound once.
+   *    <path/> The relative path to the audio file.
+   *    <property/> Take action if this property becomes true.
+   *    <condition/> Take action if this condition becomes true.
+   *    <volume> or <pitch> Define volume or pitch settings.
+   *     <property/> Take the value of this property as a refference for the
+   *                 result.
+   *     <internal/> Either:
+   *                   dt_start: the time elapsed since this sound is playing.
+   *                   dt_stop: the time elapsed since this sound has stopped.
+   *     <offset/> Add this value to the result.
+   *     <factor/> Multiply the result by this factor.
+   *     <min/> Make sure the value is never less than this value.
+   *     <max/> Make sure the value is never larger than this value.
+   *    </volume> or </pitch>
+   *   </event_name>
+   *
+   *   <event_name>
+   *   </event_name>
+   *  </fx>
+   *
+   * @param root The root node of the programs property tree.
+   * @param child A pointer to the location of the current event as defined
+   * in the configuration file.
+   * @param sndmgr A pointer to a pre-initialized sound manager class.
+   * @param path The path where the audio files remain.
+   */
   virtual void init (SGPropertyNode *, SGPropertyNode *, SGSoundMgr *,
                      const string &);
+
+  /**
+   * Check wheter an event has happened and if action has to be taken.
+   */
   virtual void update (double dt);
 
+  /**
+   * Stop taking action on the pre-defined events.
+   */
   void stop();
 
 protected:

simgear/sound/soundmgr.hxx

@@ -69,28 +69,80 @@ public:
     SGSimpleSound( unsigned char *buffer, int len );
     ~SGSimpleSound();
 
+    /**
+     * Start playing this sample.
+     *
+     * @param sched A pointer to the appropriate scheduler.
+     * @param looped Define wether the sound should be played in a loop.
+     */
     void play( slScheduler *sched, bool looped );
-    void stop( slScheduler *sched, bool quick = true );
 
+    /**
+     * Stop playing this sample.
+     *
+     * @param sched A pointer to the appropriate scheduler.
+     */
+    void stop( slScheduler *sched );
+
+    /**
+     * Play this sample once.
+     * @see #play
+     */
     inline void play_once( slScheduler *sched ) { play( sched, false); }
+
+    /** 
+     * Play this sample looped.
+     * @see #play
+     */
     inline void play_looped( slScheduler *sched ) { play( sched, true); }
+
+    /**
+     * Test if a sample is curretnly playing.
+     * @return true if is is playing, false otherwise.
+     */
     inline bool is_playing( ) {
         return ( sample->getPlayCount() > 0 );
     }
 
+    /**
+     * Get the current pitch setting of this sample.
+     */
     inline double get_pitch() const { return pitch; }
+
+    /**
+     * Set the pitch of this sample.
+     */
     inline void set_pitch( double p ) {
        pitch = p;
        pitch_envelope->setStep( 0, 0.01, pitch );
     }
+
+    /**
+     * Get the current volume setting of this sample.
+     */
     inline double get_volume() const { return volume; }
+
+    /**
+     * Set the volume of this sample.
+     */
     inline void set_volume( double v ) {
        volume = v;
        volume_envelope->setStep( 0, 0.01, volume );
     }
 
+    /**
+     * Get a refference to the raw sample.
+     */
     inline slSample *get_sample() { return sample; }
+
+    /**
+     * Get the pitch envelope setting of this sample.
+     */
     inline slEnvelope *get_pitch_envelope() { return pitch_envelope; }
+
+    /**
+     * Get the volume envelope setting of this sample.
+     */
     inline slEnvelope *get_volume_envelope() { return volume_envelope; }
 };
 
@@ -181,7 +233,16 @@ public:
     bool add( SGSimpleSound *sound, const string& refname);
 
     /**
-     * add a sound file, return the sample if successful, else return NULL
+     * Add a sound file to the sound manager.
+     *
+     * The advantage of using this function over the previous one is that
+     * it doesn't load a sample if it already is in memory, but instead it
+     * uses the already loaded sample data.
+     *
+     * @param refname A refference name to make a distincion between samples.
+     * @param path The path or full filename of the sample to load.
+     * @param file An optional filename which will be appended to the path.
+     * @return An instance of the sound for further manipulation.
      */
     SGSimpleSound *add( const string& refname,
                       const char *path, const char *file = NULL );