Clean

audio.h

@@ -1,5 +1,10 @@
-/**
-  audio: this file implements the audio system.
+/*
+  Licar audio
+
+  This file implements the audio system. The module only computes audio samples
+  (playing them must be done by the frontend). The audio format is 8bit, 8 KHz
+  mono. This module does NOT deal with music (music is stored in a separate
+  file, left to be optionally loaded and played by the frontend).
 */
 
 #ifndef _LCR_AUDIO
@@ -26,6 +31,9 @@ struct
   int engineInc;
 } LCR_audio;
 
+/**
+  Initializes the audio system, only call once.
+*/
 void LCR_audioInit(void)
 {
   LCR_LOG0("initializing audio");
@@ -40,11 +48,18 @@ void LCR_audioInit(void)
   LCR_audio.engineIntensity = 0;
 }
 
+/**
+  Sets the intensity of car engine sound that's constantly played (unless when
+  intensitiy has been set to 0). Maximum value is 255.
+*/
 void LCR_audioSetEngineIntensity(uint8_t value)
 {
   LCR_audio.engineIntensity = value;
 }
 
+/**
+  Tells the audio system to play certain sound (see the sound constants).
+*/
 void LCR_audioPlaySound(uint8_t sound)
 {
   LCR_LOG2("playing sound");
@@ -58,6 +73,9 @@ uint8_t _LCR_audioNoise(void)
   return LCR_audio.noise >> 16;
 }
 
+/**
+  Gets the next audio sample.
+*/
 uint8_t LCR_audioGetNextSample(void)
 {
   unsigned char result = 128;