Index: libreplaygain/include/replaygain/gain_analysis.h
===================================================================
--- libreplaygain/include/replaygain/gain_analysis.h	(revision 231)
+++ libreplaygain/include/replaygain/gain_analysis.h	(revision 403)
@@ -26,4 +26,22 @@
  */
 
+/**
+ * Pseudo-code to process an album:
+ *
+ *    Float_t       l_samples [4096];
+ *    Float_t       r_samples [4096];
+ *    size_t        num_samples;
+ *    unsigned int  num_songs;
+ *    unsigned int  i;
+ *
+ *    gain_init_analysis ( 44100 );
+ *    for ( i = 1; i <= num_songs; i++ ) {
+ *        while ( ( num_samples = getSongSamples ( song[i], left_samples, right_samples ) ) > 0 )
+ *            gain_analyze_samples ( left_samples, right_samples, num_samples, 2 );
+ *        fprintf ("Recommended dB change for song %2d: %+6.2f dB\n", i, gain_get_title() );
+ *    }
+ *    fprintf ("Recommended dB change for whole album: %+6.2f dB\n", gain_get_album() );
+ */
+
 #ifndef GAIN_ANALYSIS_H
 #define GAIN_ANALYSIS_H
@@ -44,9 +62,19 @@
 typedef double  Float_t;         // Type used for filtering
 
-int     InitGainAnalysis ( long samplefreq );
-int     AnalyzeSamples   ( const Float_t* left_samples, const Float_t* right_samples, size_t num_samples, int num_channels );
-int	ResetSampleFrequency ( long samplefreq );
-Float_t   GetTitleGain     ( void );
-Float_t   GetAlbumGain     ( void );
+/// Here's the deal : Call
+int gain_init_analysis ( long samplefreq );
+/// to initialize everything. Call
+int gain_analyze_samples ( const Float_t* left_samples, const Float_t* right_samples, size_t num_samples, int num_channels );
+/// as many times as you want, with as many or as few samples as you want.
+/// If mono, pass the sample buffer in through left_samples, leave
+/// right_samples NULL, and make sure num_channels = 1.
+
+Float_t gain_get_title ( void );
+/// will return the recommended dB level change for all samples analyzed
+/// SINCE THE LAST TIME you called gain_get_title() OR gain_init_analysis().
+
+Float_t gain_get_album ( void );
+/// will return the recommended dB level change for all samples analyzed
+/// since gain_init_analysis() was called and finalized with gain_get_title().
 
 #ifdef __cplusplus