From 6e818d42f4c1abd7a668c94ff227a2e5e7e40c95 Mon Sep 17 00:00:00 2001 From: tpoole Date: Tue, 1 Aug 2017 11:22:55 +0100 Subject: [PATCH] Documentation fixes --- modules/juce_dsp/containers/juce_AudioBlock.h | 10 ++-- .../juce_dsp/containers/juce_SIMDRegister.h | 47 ++++++++++--------- .../filter_design/juce_FilterDesign.h | 38 +++++++++------ .../native/juce_fallback_SIMDNativeOps.h | 4 +- modules/juce_dsp/processors/juce_Gain.h | 1 + modules/juce_dsp/processors/juce_IIRFilter.h | 2 +- modules/juce_dsp/processors/juce_Oscillator.h | 6 +-- .../processors/juce_StateVariableFilter.h | 2 +- 8 files changed, 60 insertions(+), 50 deletions(-) diff --git a/modules/juce_dsp/containers/juce_AudioBlock.h b/modules/juce_dsp/containers/juce_AudioBlock.h index db85362002..cd4ccd2daa 100644 --- a/modules/juce_dsp/containers/juce_AudioBlock.h +++ b/modules/juce_dsp/containers/juce_AudioBlock.h @@ -420,13 +420,13 @@ public: return *this; } - /* negates each value of the receiver */ + /** Negates each value of the receiver. */ forcedinline AudioBlock& negate() noexcept { return multiply (static_cast (-1.0)); } - /* Negates each value of source and stores it in the receiver */ + /** Negates each value of source and stores it in the receiver. */ forcedinline AudioBlock& replaceWithNegativeOf (const AudioBlock& src) noexcept { jassert (numChannels == src.numChannels); @@ -438,7 +438,7 @@ public: return *this; } - /* takes the absolute value of each element of src and stores it inside the receiver. */ + /** Takes the absolute value of each element of src and stores it inside the receiver. */ forcedinline AudioBlock& replaceWithAbsoluteValueOf (const AudioBlock& src) noexcept { jassert (numChannels == src.numChannels); @@ -462,7 +462,7 @@ public: return *this; } - /** Each element of receiver will be the maximum of the corresponding element of the source arrays. */ + /** Each element of the receiver will be the maximum of the corresponding element of the source arrays. */ forcedinline AudioBlock& max (AudioBlock src1, AudioBlock src2) noexcept { jassert (numChannels == src1.numChannels && src1.numChannels == src2.numChannels); @@ -474,7 +474,7 @@ public: return *this; } - /** Find minimum and maximum value of the buffer. */ + /** Finds the minimum and maximum value of the buffer. */ forcedinline Range findMinAndMax() const noexcept { Range minmax; diff --git a/modules/juce_dsp/containers/juce_SIMDRegister.h b/modules/juce_dsp/containers/juce_SIMDRegister.h index 06e73e983f..059f5c5bef 100644 --- a/modules/juce_dsp/containers/juce_SIMDRegister.h +++ b/modules/juce_dsp/containers/juce_SIMDRegister.h @@ -95,7 +95,7 @@ struct SIMDRegister vSIMDType value; //============================================================================== - /** Returns the number of elements in this vector */ + /** Returns the number of elements in this vector. */ static constexpr size_t size() noexcept { return SIMDNumElements; } //============================================================================== @@ -108,7 +108,7 @@ struct SIMDRegister inline static SIMDRegister JUCE_VECTOR_CALLTYPE fromNative (vSIMDType a) noexcept { return {a}; } //============================================================================== - /** Return the idx-th element of the receiver. Note that this does not check if idx + /** Returns the idx-th element of the receiver. Note that this does not check if idx is larger than the native register size. */ inline Type JUCE_VECTOR_CALLTYPE operator[] (size_t idx) const noexcept { @@ -116,7 +116,7 @@ struct SIMDRegister return reinterpret_cast (&value) [idx]; } - /** Return the idx-th element of the receiver. Note that this does not check if idx + /** Returns the idx-th element of the receiver. Note that this does not check if idx is larger than the native register size. */ inline Type& JUCE_VECTOR_CALLTYPE operator[] (size_t idx) noexcept { @@ -125,26 +125,26 @@ struct SIMDRegister } //============================================================================== - /** Add another SIMDRegister to the receiver. */ + /** Adds another SIMDRegister to the receiver. */ inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator+= (SIMDRegister v) noexcept { value = NativeOps::add (value, v.value); return *this; } - /** Subtract another SIMDRegister to the receiver. */ + /** Subtracts another SIMDRegister to the receiver. */ inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator-= (SIMDRegister v) noexcept { value = NativeOps::sub (value, v.value); return *this; } - /** Subtract another SIMDRegister to the receiver. */ + /** Subtracts another SIMDRegister to the receiver. */ inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator*= (SIMDRegister v) noexcept { value = CmplxOps::mul (value, v.value); return *this; } //============================================================================== /** Broadcasts the scalar to all elements of the receiver. */ inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator= (Type s) noexcept { value = CmplxOps::expand (s); return *this; } - /** Add a scalar to the receiver. */ + /** Adds a scalar to the receiver. */ inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator+= (Type s) noexcept { value = NativeOps::add (value, CmplxOps::expand (s)); return *this; } - /** Subtract a scalar to the receiver. */ + /** Subtracts a scalar to the receiver. */ inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator-= (Type s) noexcept { value = NativeOps::sub (value, CmplxOps::expand (s)); return *this; } - /** Multiply a scalar to the receiver. */ + /** Multiplies a scalar to the receiver. */ inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator*= (Type s) noexcept { value = CmplxOps::mul (value, CmplxOps::expand (s)); return *this; } //============================================================================== @@ -168,46 +168,46 @@ struct SIMDRegister inline SIMDRegister& JUCE_VECTOR_CALLTYPE operator^= (MaskType s) noexcept { value = NativeOps::bit_xor (value, toVecType (s)); return *this; } //============================================================================== - /** Return the sum of the receiver and v.*/ + /** Returns the sum of the receiver and v.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator+ (SIMDRegister v) const noexcept { return { NativeOps::add (value, v.value) }; } - /** Return the difference of the receiver and v.*/ + /** Returns the difference of the receiver and v.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator- (SIMDRegister v) const noexcept { return { NativeOps::sub (value, v.value) }; } - /** Return the product of the receiver and v.*/ + /** Returns the product of the receiver and v.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator* (SIMDRegister v) const noexcept { return { CmplxOps::mul (value, v.value) }; } //============================================================================== - /** Return a vector where each element is the sum of the corresponding element in the receiver and the scalar s.*/ + /** Returns a vector where each element is the sum of the corresponding element in the receiver and the scalar s.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator+ (Type s) const noexcept { return { NativeOps::add (value, CmplxOps::expand (s)) }; } - /** Return a vector where each element is the difference of the corresponding element in the receiver and the scalar s.*/ + /** Returns a vector where each element is the difference of the corresponding element in the receiver and the scalar s.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator- (Type s) const noexcept { return { NativeOps::sub (value, CmplxOps::expand (s)) }; } - /** Return a vector where each element is the difference of the corresponding element in the receiver and the scalar s.*/ + /** Returns a vector where each element is the difference of the corresponding element in the receiver and the scalar s.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator* (Type s) const noexcept { return { CmplxOps::mul (value, CmplxOps::expand (s)) }; } //============================================================================== - /** Return the bit-and of the receiver and v. */ + /** Returns the bit-and of the receiver and v. */ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator& (vMaskType v) const noexcept { return { NativeOps::bit_and (value, toVecType (v.value)) }; } - /** Return the bit-or of the receiver and v. */ + /** Returns the bit-or of the receiver and v. */ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator| (vMaskType v) const noexcept { return { NativeOps::bit_or (value, toVecType (v.value)) }; } - /** Return the bit-xor of the receiver and v. */ + /** Returns the bit-xor of the receiver and v. */ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator^ (vMaskType v) const noexcept { return { NativeOps::bit_xor (value, toVecType (v.value)) }; } - /** Return a vector where each element is the bit-inverted value of the corresponding element in the receiver.*/ + /** Returns a vector where each element is the bit-inverted value of the corresponding element in the receiver.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator~ () const noexcept { return { NativeOps::bit_not (value) }; } //============================================================================== - /** Return a vector where each element is the bit-and'd value of the corresponding element in the receiver and the scalar s.*/ + /** Returns a vector where each element is the bit-and'd value of the corresponding element in the receiver and the scalar s.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator& (MaskType s) const noexcept { return { NativeOps::bit_and (value, toVecType (s)) }; } - /** Return a vector where each element is the bit-or'd value of the corresponding element in the receiver and the scalar s.*/ + /** Returns a vector where each element is the bit-or'd value of the corresponding element in the receiver and the scalar s.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator| (MaskType s) const noexcept { return { NativeOps::bit_or (value, toVecType (s)) }; } - /** Return a vector where each element is the bit-xor'd value of the corresponding element in the receiver and the scalar s.*/ + /** Returns a vector where each element is the bit-xor'd value of the corresponding element in the receiver and the scalar s.*/ inline SIMDRegister JUCE_VECTOR_CALLTYPE operator^ (MaskType s) const noexcept { return { NativeOps::bit_xor (value, toVecType (s)) }; } //============================================================================== @@ -318,6 +318,7 @@ private: //============================================================================== /* This class is used internally by SIMDRegister to abstract away differences in operations which are different for complex and pure floating point types. */ + // the pure floating-point version template struct CmplxSIMDOps @@ -345,7 +346,7 @@ struct CmplxSIMDOps } }; -// the pure complex version +// The pure complex version template struct CmplxSIMDOps > { diff --git a/modules/juce_dsp/filter_design/juce_FilterDesign.h b/modules/juce_dsp/filter_design/juce_FilterDesign.h index fbcec2dfa6..abc19aff2c 100644 --- a/modules/juce_dsp/filter_design/juce_FilterDesign.h +++ b/modules/juce_dsp/filter_design/juce_FilterDesign.h @@ -25,12 +25,12 @@ */ -/* +/** This class provides a set of functions which generates FIR::Coefficients and IIR::Coefficients, of high-order lowpass filters. They can be used for processing directly audio as an equalizer, in resampling algorithms etc. - see @FIRFilter::Coefficients, @FIRFilter, @WindowingFunction, @IIRFilter::Coefficients, @IIRFilter + see FIRFilter::Coefficients, FIRFilter, WindowingFunction, IIRFilter::Coefficients, IIRFilter */ template struct FilterDesign @@ -41,7 +41,7 @@ struct FilterDesign using WindowingMethod = typename WindowingFunction::WindowingMethod; //============================================================================== - /* This method generates a FIR::Coefficients for a low-pass filter, using + /** This method generates a FIR::Coefficients for a low-pass filter, using the windowing design method, applied to a sinc impulse response. It is one of the simplest method used to generate a high order low-pass filter, which has the downside of needing more coefficients than more complex method to @@ -56,7 +56,7 @@ struct FilterDesign @param frequency the cutoff frequency of the low-pass filter @param sampleRate the sample rate being used in the filter design @param order the order of the filter - @param type the type, must be a @WindowingFunction::WindowingType + @param type the type, must be a WindowingFunction::WindowingType @param beta an optional additional parameter useful for the Kaiser windowing function */ @@ -64,7 +64,7 @@ struct FilterDesign size_t order, WindowingMethod type, FloatType beta = static_cast (2)); - /* This a variant of the function @designFIRLowpassWindowMethod, which allows the + /** This a variant of the function designFIRLowpassWindowMethod, which allows the user to specify a transition width and an attenuation in dB, to get a low-pass filter using the Kaiser windowing function, with calculated values of the filter order and of the beta parameter, to satisfy the constraints. @@ -83,7 +83,7 @@ struct FilterDesign FloatType attenuationdB); - /* This method is also a variant of the function @designFIRLowpassWindowMethod, using + /** This method is also a variant of the function designFIRLowpassWindowMethod, using a rectangular window as a basis, and a spline transition between the pass band and the stop band, to reduce the Gibbs phenomenon. @@ -102,7 +102,7 @@ struct FilterDesign FloatType normalizedTransitionWidth, FloatType spline); - /* This method generates a FIR::Coefficients for a low-pass filter, by + /** This method generates a FIR::Coefficients for a low-pass filter, by minimizing the average error between the generated filter and an ideal one using the least squares error criterion and matrices operations. @@ -113,7 +113,7 @@ struct FilterDesign @param order the order of the filter @param normalizedTransitionWidth the normalized size between 0 and 0.5 of the transition between the pass band and the stop band - @param stopbandWeight between 1.0 and 100.0, indicates how much we want + @param stopBandWeight between 1.0 and 100.0, indicates how much we want attenuation in the stop band, against some oscillation in the pass band */ @@ -121,7 +121,7 @@ struct FilterDesign FloatType normalizedTransitionWidth, FloatType stopBandWeight); - /* This method generates a FIR::Coefficients for a low-pass filter, with + /** This method generates a FIR::Coefficients for a low-pass filter, with a cutoff frequency at half band, using an algorithm described in the article "Design of Half-Band FIR Filters for Signal Compression" from Pavel Zahradnik, to get an equiripple like high order FIR filter, without the need @@ -137,7 +137,7 @@ struct FilterDesign FloatType attenuationdB); //============================================================================== - /* This method returns an array of IIR::Coefficients, made to be used in + /** This method returns an array of IIR::Coefficients, made to be used in cascaded IIRFilters, providing a minimum phase lowpass filter without any ripple in the pass band and in the stop band. @@ -146,6 +146,8 @@ struct FilterDesign @param frequency the cutoff frequency of the low-pass filter @param sampleRate the sample rate being used in the filter design + @param normalizedTransitionWidth the normalized size between 0 and 0.5 of the transition + between the pass band and the stop band @param passbandAttenuationdB the lowest attenuation in dB expected in the pass band @param stopbandAttenuationdB the attenuation in dB expected in the stop band */ @@ -155,7 +157,7 @@ struct FilterDesign FloatType passbandAttenuationdB, FloatType stopbandAttenuationdB); - /* This method returns an array of IIR::Coefficients, made to be used in + /** This method returns an array of IIR::Coefficients, made to be used in cascaded IIRFilters, providing a minimum phase lowpass filter without any ripple in the stop band only. @@ -164,6 +166,8 @@ struct FilterDesign @param frequency the cutoff frequency of the low-pass filter @param sampleRate the sample rate being used in the filter design + @param normalizedTransitionWidth the normalized size between 0 and 0.5 of the transition + between the pass band and the stop band @param passbandAttenuationdB the lowest attenuation in dB expected in the pass band @param stopbandAttenuationdB the attenuation in dB expected in the stop band */ @@ -172,7 +176,7 @@ struct FilterDesign FloatType passbandAttenuationdB, FloatType stopbandAttenuationdB); - /* This method returns an array of IIR::Coefficients, made to be used in + /** This method returns an array of IIR::Coefficients, made to be used in cascaded IIRFilters, providing a minimum phase lowpass filter without any ripple in the pass band only. @@ -181,6 +185,8 @@ struct FilterDesign @param frequency the cutoff frequency of the low-pass filter @param sampleRate the sample rate being used in the filter design + @param normalizedTransitionWidth the normalized size between 0 and 0.5 of the transition + between the pass band and the stop band @param passbandAttenuationdB the lowest attenuation in dB expected in the pass band @param stopbandAttenuationdB the attenuation in dB expected in the stop band */ @@ -189,7 +195,7 @@ struct FilterDesign FloatType passbandAttenuationdB, FloatType stopbandAttenuationdB); - /* This method returns an array of IIR::Coefficients, made to be used in + /** This method returns an array of IIR::Coefficients, made to be used in cascaded IIR::Filters, providing a minimum phase lowpass filter with ripples in both the pass band and in the stop band. @@ -198,6 +204,8 @@ struct FilterDesign @param frequency the cutoff frequency of the low-pass filter @param sampleRate the sample rate being used in the filter design + @param normalizedTransitionWidth the normalized size between 0 and 0.5 of the transition + between the pass band and the stop band @param passbandAttenuationdB the lowest attenuation in dB expected in the pass band @param stopbandAttenuationdB the attenuation in dB expected in the stop band */ @@ -216,7 +224,7 @@ struct FilterDesign */ struct IIRPolyphaseAllpassStructure { Array directPath, delayedPath; }; - /* This method generates arrays of IIR::Coefficients for a low-pass filter, with + /** This method generates arrays of IIR::Coefficients for a low-pass filter, with a cutoff frequency at half band, using an algorithm described in the article "Digital Signal Processing Schemes for efficient interpolation and decimation" from Pavel Valenzuela and Constantinides. @@ -234,7 +242,7 @@ struct FilterDesign @param normalizedTransitionWidth the normalized size between 0 and 0.5 of the transition between the pass band and the stop band - @param attenuationdB the attenuation in dB expected in the stop band + @param stopbandAttenuationdB the attenuation in dB expected in the stop band */ static IIRPolyphaseAllpassStructure designIIRLowpassHalfBandPolyphaseAllpassMethod (FloatType normalizedTransitionWidth, FloatType stopbandAttenuationdB); diff --git a/modules/juce_dsp/native/juce_fallback_SIMDNativeOps.h b/modules/juce_dsp/native/juce_fallback_SIMDNativeOps.h index bf371b6db4..da3f92965d 100644 --- a/modules/juce_dsp/native/juce_fallback_SIMDNativeOps.h +++ b/modules/juce_dsp/native/juce_fallback_SIMDNativeOps.h @@ -47,8 +47,8 @@ namespace SIMDInternal } /** - Useful fallback routines to use if the native SIMD op is not supported. You - should never need to use this directly. Use juce_SIMDRegister instead. + Useful fallback routines to use if the native SIMD op is not supported. You + should never need to use this directly. Use juce_SIMDRegister instead. */ template struct SIMDFallbackOps diff --git a/modules/juce_dsp/processors/juce_Gain.h b/modules/juce_dsp/processors/juce_Gain.h index 408043af6d..cfa2b1dcf8 100644 --- a/modules/juce_dsp/processors/juce_Gain.h +++ b/modules/juce_dsp/processors/juce_Gain.h @@ -57,6 +57,7 @@ public: } } + /** Returns the ramp duration in seconds. */ double getRampDurationSeconds() const noexcept { return rampDurationSeconds; } /** Returns true if the current value is currently being interpolated. */ diff --git a/modules/juce_dsp/processors/juce_IIRFilter.h b/modules/juce_dsp/processors/juce_IIRFilter.h index 23bffa8144..2c5e5980fd 100644 --- a/modules/juce_dsp/processors/juce_IIRFilter.h +++ b/modules/juce_dsp/processors/juce_IIRFilter.h @@ -90,7 +90,7 @@ namespace IIR /** Resets the filter's processing pipeline to a specific value. - See @reset + @see reset */ void reset (SampleType resetToValue); diff --git a/modules/juce_dsp/processors/juce_Oscillator.h b/modules/juce_dsp/processors/juce_Oscillator.h index a0b3fdcbda..9230658951 100644 --- a/modules/juce_dsp/processors/juce_Oscillator.h +++ b/modules/juce_dsp/processors/juce_Oscillator.h @@ -37,10 +37,10 @@ public: */ using NumericType = typename SampleTypeHelpers::ElementType::Type; - /* Create an oscillator with a periodic input function (-pi..pi). + /** Creates an oscillator with a periodic input function (-pi..pi). - If lookup table is not zero, then the function will be approximated - with a lookup table. + If lookup table is not zero, then the function will be approximated + with a lookup table. */ Oscillator (const std::function& function, size_t lookupTableNumPoints = 0) : generator (function), frequency (440.0f) diff --git a/modules/juce_dsp/processors/juce_StateVariableFilter.h b/modules/juce_dsp/processors/juce_StateVariableFilter.h index 88a75bb972..98d3d4750b 100644 --- a/modules/juce_dsp/processors/juce_StateVariableFilter.h +++ b/modules/juce_dsp/processors/juce_StateVariableFilter.h @@ -168,7 +168,7 @@ namespace StateVariableFilter /** The type of the IIR filter */ Type type = Type::lowPass; - /** Set the cutoff frequency and resonance of the IIR filter. + /** Sets the cutoff frequency and resonance of the IIR filter. Note : the bandwidth of the resonance increases with the value of the parameter. To have a standard 12 dB/octave filter, the value must be set at 1 / sqrt(2).