Better documentation of ITAAudioSample and removed unnecessary methods

include/ITAAudioSample.h

@@ -25,22 +25,28 @@
 
 #include <string>
 
-//! Multi-channel audio sample with floating point quantization
+//! Multi-channel audio sample with single precision floating point quantization
 /**
-  * ITASampleFrame with a sampling rate. Also converts from other sampling rates.
+  * An audio sample is basically an ITASampleFrame with a given sampling rate.
   */
 class ITA_BASE_API CITAAudioSample : public ITASampleFrame
 {
 public:
 	//! Create empty audio sample
 	/**
-	  * Requires initialization or load to be used, otherwise methods will throw ITAException.
+	  * Creates an uninitialized audio sample with given a sampling rate, only.
+	  *
+	  * @note Requires initialization or load to be used, otherwise methods will throw ITAException.
 	  */
 	CITAAudioSample( const float fSampleRate = 44100.0f );
 	
 	//! Create audio sample from file
 	/**
-	  * Requires initialization or load to be used, otherwise methods will throw ITAException.
+	  * Will load audio sample from file and adopts number of channels and sample rate.
+	  *
+	  * @param[in] sFilePath Path to audio file
+	  *
+	  * @note Will raise ITAException on error.
 	  */
 	CITAAudioSample( const std::string& sFilePath );
 
@@ -51,23 +57,27 @@ public:
 	  * @param[in] fSampleRate Sampling rate of audio sample
 	  * @param[in] bZeroInit	   Init with zeros
 	  */
-	explicit CITAAudioSample( const int iChannels, const int iLength, const float fSampleRate, const bool bZeroInit = true );
+	explicit CITAAudioSample( const int iNumChannels, const int iLengthSamples, const float fSampleRate, const bool bZeroInit = true );
 
 	//! Copy constructor as pointer
 	/**
-	 * \param pSource Pointer to source audio sample
+	 * @param[in] pSource Pointer to source audio sample
 	 */
 	CITAAudioSample( const CITAAudioSample* pSource );
 
 	//! Copy constructor as reference
 	/**
-	  * \param pbSource Reference to source audio sample
+	  * @param[in] pbSource Reference to source audio sample
 	  */
 	CITAAudioSample( const CITAAudioSample& sbSource );
 
 	virtual inline ~CITAAudioSample() {};
 
 	//! Sampling frequency of audio sample
+	/**
+	  * @return Sampling rate of audio sample
+	  *
+	  */
 	float GetSampleRate() const;
 	
 	//! Initialize
@@ -81,21 +91,45 @@ public:
 	  */
 	void Init( const int iNumChannels, const int iLengthSamples, const float fSampleRate, const bool bZeroInit = true );
 
-	//! Read from sample buffer with sample rate conversion
+	//! Read from sample buffer with sample rate conversion, if necessary
+	/**
+	  * Reads audio samples from sample frame and converts to internal sample rate, if given source sample rate is mismatching.
+	  *
+	  * @param[in] sfSource Source sample frame
+	  * @param[in] fSourceSampleRate Sample rate of source sample frame
+	  *
+	  */
 	void Load( const ITASampleFrame& sfSource, const float fSourceSampleRate );
 
-	//! Read from other audio sample with sample rate conversion
+	//! Read from other audio sample with sample rate conversion, if necessary
+	/**
+	  * Reads audio samples from sample frame and converts to internal sample rate, if given source sample rate is mismatching.
+	  *
+	  * @param[in] oSource Source audio sample
+	  */
 	void Load( const CITAAudioSample& oSource );
 
-	//! Load audio sample from file and inherit it's sample rate
+	//! Load audio sample from file and adopt it's sample rate
+	/**
+	  * Will load audio sample from file and adopts number of channels and sample rate.
+	  *
+	  * @param[in] sFilePath Path to audio file
+	  *
+	  * @note Will raise ITAException on error.
+	  * @sa LoadWithSampleRateConversion()
+	  */
 	void Load( const std::string& sFilePath );
 
-	//! Load audio sample from file and convert sample rate, if necessary
+	//! Load audio sample from file and convert sample rate to internal sample rate, if necessary
+	/**
+	  * Will load audio sample from file and adopts number of channels but not sample rate. Converts audio samples into internal sampling rate if mismatched.
+	  *
+	  * @param[in] sFilePath Path to audio file
+	  *
+	  * @note Will raise ITAException on error.
+	  */
 	void LoadWithSampleRateConversion( const std::string& sFilePath );
 
-	//! Load audio sample from file and convert sample rate, if necessary
-	void LoadWithSampleRateConversion( const CITAAudioSample& asSource );
-
 private:
 
 	//! Disable this Init method from sample buffer

src/ITAAudioSample.cpp

@@ -52,18 +52,11 @@ void CITAAudioSample::LoadWithSampleRateConversion( const std::string& sFilePath
 		Load( sfRaw, GetSampleRate() );
 }
 
-void CITAAudioSample::LoadWithSampleRateConversion( const CITAAudioSample& asSource )
-{
-	ITASampleFrame* psfSource = ( ITASampleFrame* ) &asSource;
-	Load( *psfSource, asSource.GetSampleRate() );
-}
-
 void CITAAudioSample::Load( const CITAAudioSample& oSource )
 {
 	Load( oSource, oSource.GetSampleRate() );
 }
 
-
 void CITAAudioSample::Load( const std::string& sFilePath )
 {
 	double dSampleRate;