3D Audio GSoC:

Code documentation.

Also:
* Fix: rlint for MSVC.
* Minor other small fixes/changes.

18 files changed, 72 insertions, 25 deletions

diff --git a/intern/audaspace/FX/AUD_AccumulatorFactory.h b/intern/audaspace/FX/AUD_AccumulatorFactory.h
index 5838ccee7f0..95246ef5341 100644
--- a/intern/audaspace/FX/AUD_AccumulatorFactory.h
+++ b/intern/audaspace/FX/AUD_AccumulatorFactory.h
@@ -37,6 +37,10 @@ class AUD_CallbackIIRFilterReader;
 
 /**
  * This factory creates an accumulator reader.
+ *
+ * The accumulator adds the difference at the input to the last output in case
+ * it's positive. In additive mode it additionaly adds the difference always.
+ * So in case the difference is positive, it's added twice.
  */
 class AUD_AccumulatorFactory : public AUD_EffectFactory
 {
diff --git a/intern/audaspace/FX/AUD_BaseIIRFilterReader.h b/intern/audaspace/FX/AUD_BaseIIRFilterReader.h
index 644bcffbfaf..6bf877d66da 100644
--- a/intern/audaspace/FX/AUD_BaseIIRFilterReader.h
+++ b/intern/audaspace/FX/AUD_BaseIIRFilterReader.h
@@ -97,11 +97,21 @@ protected:
 	void setLengths(int in, int out);
 
 public:
+	/**
+	 * Retrieves the last input samples.
+	 * \param pos The position, valid are 0 (current) or negative values.
+	 * \return The sample value.
+	 */
 	inline sample_t x(int pos)
 	{
 		return m_x[(m_xpos + pos + m_xlen) % m_xlen * m_specs.channels + m_channel];
 	}
 
+	/**
+	 * Retrieves the last output samples.
+	 * \param pos The position, valid are negative values.
+	 * \return The sample value.
+	 */
 	inline sample_t y(int pos)
 	{
 		return m_y[(m_ypos + pos + m_ylen) % m_ylen * m_specs.channels + m_channel];
@@ -111,7 +121,16 @@ public:
 
 	virtual void read(int& length, bool& eos, sample_t* buffer);
 
+	/**
+	 * Runs the filtering function.
+	 * \return The current output sample value.
+	 */
 	virtual sample_t filter()=0;
+
+	/**
+	 * Notifies the filter about a sample rate change.
+	 * \param rate The new sample rate.
+	 */
 	virtual void sampleRateChanged(AUD_SampleRate rate);
 };
 
diff --git a/intern/audaspace/FX/AUD_ButterworthFactory.h b/intern/audaspace/FX/AUD_ButterworthFactory.h
index 16d0b3dbc23..12d28eb4038 100644
--- a/intern/audaspace/FX/AUD_ButterworthFactory.h
+++ b/intern/audaspace/FX/AUD_ButterworthFactory.h
@@ -35,7 +35,7 @@
 #include "AUD_DynamicIIRFilterFactory.h"
 
 /**
- * This factory creates a butterworth filter reader.
+ * This factory creates a butterworth lowpass filter reader.
  */
 class AUD_ButterworthFactory : public AUD_DynamicIIRFilterFactory
 {
diff --git a/intern/audaspace/FX/AUD_DelayReader.h b/intern/audaspace/FX/AUD_DelayReader.h
index a89afe73b37..128e589eede 100644
--- a/intern/audaspace/FX/AUD_DelayReader.h
+++ b/intern/audaspace/FX/AUD_DelayReader.h
@@ -36,7 +36,7 @@
 #include "AUD_Buffer.h"
 
 /**
- * This class reads another reader and changes it's delay.
+ * This class reads another reader and delays it.
  */
 class AUD_DelayReader : public AUD_EffectReader
 {
diff --git a/intern/audaspace/FX/AUD_DoubleFactory.h b/intern/audaspace/FX/AUD_DoubleFactory.h
index f2be7132442..2db2257244c 100644
--- a/intern/audaspace/FX/AUD_DoubleFactory.h
+++ b/intern/audaspace/FX/AUD_DoubleFactory.h
@@ -36,7 +36,6 @@
 
 /**
  * This factory plays two other factories behind each other.
- * \note Readers from the underlying factories must have the same sample rate and channel count.
  */
 class AUD_DoubleFactory : public AUD_IFactory
 {
diff --git a/intern/audaspace/FX/AUD_DoubleReader.h b/intern/audaspace/FX/AUD_DoubleReader.h
index 86f636e2cb2..750868a9400 100644
--- a/intern/audaspace/FX/AUD_DoubleReader.h
+++ b/intern/audaspace/FX/AUD_DoubleReader.h
@@ -37,7 +37,7 @@
 #include "AUD_Reference.h"
 
 /**
- * This reader plays two readers with the same specs sequently.
+ * This reader plays two readers sequently.
  */
 class AUD_DoubleReader : public AUD_IReader
 {
@@ -57,21 +57,15 @@ private:
 	 */
 	bool m_finished1;
 
-	/**
-	 * The playback buffer for the intersecting part.
-	 */
-	AUD_Buffer m_buffer;
-
 	// hide copy constructor and operator=
 	AUD_DoubleReader(const AUD_DoubleReader&);
 	AUD_DoubleReader& operator=(const AUD_DoubleReader&);
 
 public:
 	/**
-	 * Creates a new ping pong reader.
+	 * Creates a new double reader.
 	 * \param reader1 The first reader to read from.
 	 * \param reader2 The second reader to read from.
-	 * \exception AUD_Exception Thrown if the specs from the readers differ.
 	 */
 	AUD_DoubleReader(AUD_Reference<AUD_IReader> reader1, AUD_Reference<AUD_IReader> reader2);
 
diff --git a/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h b/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h
index 19c1a0f0a54..56d56a977d4 100644
--- a/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h
+++ b/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h
@@ -34,13 +34,29 @@
 #include "AUD_EffectFactory.h"
 #include <vector>
 
+/**
+ * This factory creates a IIR filter reader.
+ *
+ * This means that on sample rate change the filter recalculates its
+ * coefficients.
+ */
 class AUD_DynamicIIRFilterFactory : public AUD_EffectFactory
 {
 public:
+	/**
+	 * Creates a new Dynmic IIR filter factory.
+	 * \param factory The input factory.
+	 */
 	AUD_DynamicIIRFilterFactory(AUD_Reference<AUD_IFactory> factory);
 
 	virtual AUD_Reference<AUD_IReader> createReader();
 
+	/**
+	 * Recalculates the filter coefficients.
+	 * \param rate The sample rate of the audio data.
+	 * \param[out] b The input filter coefficients.
+	 * \param[out] a The output filter coefficients.
+	 */
 	virtual void recalculateCoefficients(AUD_SampleRate rate,
 										 std::vector<float>& b,
 										 std::vector<float>& a)=0;
diff --git a/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h b/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h
index 92f491f04d4..42789726728 100644
--- a/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h
+++ b/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h
@@ -34,6 +34,10 @@
 #include "AUD_IIRFilterReader.h"
 #include "AUD_DynamicIIRFilterFactory.h"
 
+/**
+ * This class is for dynamic infinite impulse response filters with simple
+ * coefficients that change depending on the sample rate.
+ */
 class AUD_DynamicIIRFilterReader : public AUD_IIRFilterReader
 {
 private:
diff --git a/intern/audaspace/FX/AUD_HighpassFactory.h b/intern/audaspace/FX/AUD_HighpassFactory.h
index 51d5f55cb36..c135be27d77 100644
--- a/intern/audaspace/FX/AUD_HighpassFactory.h
+++ b/intern/audaspace/FX/AUD_HighpassFactory.h
@@ -41,7 +41,7 @@ class AUD_HighpassFactory : public AUD_DynamicIIRFilterFactory
 {
 private:
 	/**
-	 * The attack value in seconds.
+	 * The cutoff frequency.
 	 */
 	const float m_frequency;
 
diff --git a/intern/audaspace/FX/AUD_LimiterReader.h b/intern/audaspace/FX/AUD_LimiterReader.h
index d9bee6f6463..9cddd4d57ec 100644
--- a/intern/audaspace/FX/AUD_LimiterReader.h
+++ b/intern/audaspace/FX/AUD_LimiterReader.h
@@ -35,7 +35,7 @@
 #include "AUD_EffectReader.h"
 
 /**
- * This reader limits another reader in start and end sample.
+ * This reader limits another reader in start and end times.
  */
 class AUD_LimiterReader : public AUD_EffectReader
 {
@@ -58,9 +58,9 @@ public:
 	/**
 	 * Creates a new limiter reader.
 	 * \param reader The reader to read from.
-	 * \param start The desired start sample (inclusive).
-	 * \param end The desired end sample (exklusive), a negative value signals
-	 *            that it should play to the end.
+	 * \param start The desired start time (inclusive).
+	 * \param end The desired end time (sample exklusive), a negative value
+	 *            signals that it should play to the end.
 	 */
 	AUD_LimiterReader(AUD_Reference<AUD_IReader> reader, float start = 0, float end = -1);
 
diff --git a/intern/audaspace/FX/AUD_LowpassFactory.h b/intern/audaspace/FX/AUD_LowpassFactory.h
index 6558663df4e..644d25ec73d 100644
--- a/intern/audaspace/FX/AUD_LowpassFactory.h
+++ b/intern/audaspace/FX/AUD_LowpassFactory.h
@@ -41,7 +41,7 @@ class AUD_LowpassFactory : public AUD_DynamicIIRFilterFactory
 {
 private:
 	/**
-	 * The attack value in seconds.
+	 * The cutoff frequency.
 	 */
 	const float m_frequency;
 
diff --git a/intern/audaspace/FX/AUD_PingPongFactory.h b/intern/audaspace/FX/AUD_PingPongFactory.h
index 908591a6ebe..b023501d45b 100644
--- a/intern/audaspace/FX/AUD_PingPongFactory.h
+++ b/intern/audaspace/FX/AUD_PingPongFactory.h
@@ -36,7 +36,7 @@
 
 /**
  * This factory plays another factory first normal, then reversed.
- * \note Readers from the underlying factory must be from the buffer type.
+ * \note Readers from the underlying factory must be reversable with seeking.
  */
 class AUD_PingPongFactory : public AUD_EffectFactory
 {
diff --git a/intern/audaspace/FX/AUD_PitchReader.h b/intern/audaspace/FX/AUD_PitchReader.h
index 7418531ca55..ed6adbf02fb 100644
--- a/intern/audaspace/FX/AUD_PitchReader.h
+++ b/intern/audaspace/FX/AUD_PitchReader.h
@@ -53,13 +53,22 @@ public:
 	/**
 	 * Creates a new pitch reader.
 	 * \param reader The reader to read from.
-	 * \param pitch The size of the buffer.
+	 * \param pitch The pitch value.
 	 */
 	AUD_PitchReader(AUD_Reference<AUD_IReader> reader, float pitch);
 
 	virtual AUD_Specs getSpecs() const;
 
+	/**
+	 * Retrieves the pitch.
+	 * \return The current pitch value.
+	 */
 	float getPitch() const;
+
+	/**
+	 * Sets the pitch.
+	 * \param pitch The new pitch value.
+	 */
 	void setPitch(float pitch);
 };
 
diff --git a/intern/audaspace/FX/AUD_ReverseFactory.h b/intern/audaspace/FX/AUD_ReverseFactory.h
index b501b4e76c8..f43d37d8f46 100644
--- a/intern/audaspace/FX/AUD_ReverseFactory.h
+++ b/intern/audaspace/FX/AUD_ReverseFactory.h
@@ -36,7 +36,7 @@
 
 /**
  * This factory reads another factory reverted.
- * \note Readers from the underlying factory must be from the buffer type.
+ * \note Readers from the underlying factory must be seekable.
  */
 class AUD_ReverseFactory : public AUD_EffectFactory
 {
diff --git a/intern/audaspace/FX/AUD_ReverseReader.h b/intern/audaspace/FX/AUD_ReverseReader.h
index da0add9464e..197d10dfe00 100644
--- a/intern/audaspace/FX/AUD_ReverseReader.h
+++ b/intern/audaspace/FX/AUD_ReverseReader.h
@@ -37,7 +37,7 @@
 
 /**
  * This class reads another reader from back to front.
- * \note The underlying reader must be a buffer.
+ * \note The underlying reader must be seekable.
  */
 class AUD_ReverseReader : public AUD_EffectReader
 {
diff --git a/intern/audaspace/FX/AUD_SuperposeFactory.h b/intern/audaspace/FX/AUD_SuperposeFactory.h
index ac7ec080134..b12da62b497 100644
--- a/intern/audaspace/FX/AUD_SuperposeFactory.h
+++ b/intern/audaspace/FX/AUD_SuperposeFactory.h
@@ -35,8 +35,9 @@
 #include "AUD_IFactory.h"
 
 /**
- * This factory plays two other factories behind each other.
- * \note Readers from the underlying factories must have the same sample rate and channel count.
+ * This factory mixes two other factories, playing them the same time.
+ * \note Readers from the underlying factories must have the same sample rate
+ *       and channel count.
  */
 class AUD_SuperposeFactory : public AUD_IFactory
 {
diff --git a/intern/audaspace/FX/AUD_SuperposeReader.h b/intern/audaspace/FX/AUD_SuperposeReader.h
index a87f1fdb739..07b4b105835 100644
--- a/intern/audaspace/FX/AUD_SuperposeReader.h
+++ b/intern/audaspace/FX/AUD_SuperposeReader.h
@@ -37,7 +37,7 @@
 #include "AUD_Reference.h"
 
 /**
- * This reader plays two readers with the same specs sequently.
+ * This reader plays two readers with the same specs in parallel.
  */
 class AUD_SuperposeReader : public AUD_IReader
 {
@@ -53,7 +53,7 @@ private:
 	AUD_Reference<AUD_IReader> m_reader2;
 
 	/**
-	 * The playback buffer for the intersecting part.
+	 * Buffer used for mixing.
 	 */
 	AUD_Buffer m_buffer;
 
diff --git a/intern/audaspace/FX/AUD_VolumeFactory.h b/intern/audaspace/FX/AUD_VolumeFactory.h
index bcc08e7d04a..0ca0102b790 100644
--- a/intern/audaspace/FX/AUD_VolumeFactory.h
+++ b/intern/audaspace/FX/AUD_VolumeFactory.h
@@ -61,6 +61,7 @@ public:
 
 	/**
 	 * Returns the volume.
+	 * \return The current volume.
 	 */
 	float getVolume() const;