radio/blocks/signal: update docstrings for new refman generator

radio/blocks/signal/complexmagnitude.lua

@@ -2,6 +2,7 @@
 -- Compute the magnitude of a complex-valued signal.
 --
 -- $$ y[n] = |x[n]| $$
+--
 -- $$ y[n] = \sqrt{\text{Re}(x[n])^2 + \text{Im}(x[n])^2} $$
 --
 -- @category Math Operations

radio/blocks/signal/complexphase.lua

@@ -2,6 +2,7 @@
 -- Compute the argument (phase) of a complex-valued signal.
 --
 -- $$ y[n] = \text{arg}(x[n]) $$
+--
 -- $$ y[n] = \text{atan2}(\text{Im}(x[n]), \text{Re}(x[n])) $$
 --
 -- @category Math Operations

radio/blocks/signal/filter_utils.lua

@@ -1,3 +1,8 @@
+---
+-- FIR filter generation functions.
+--
+-- @module radio.blocks.signal.filter_utils
+
 local math = require('math')
 
 local window_utils = require('radio.blocks.signal.window_utils')
@@ -8,7 +13,8 @@ local window_utils = require('radio.blocks.signal.window_utils')
 ---
 -- Generate the shifted, truncated coefficients of an ideal low-pass filter.
 --
--- @local
+-- @internal
+-- @function fir_lowpass
 -- @tparam int num_taps Number of taps
 -- @tparam number cutoff Normalized cutoff frequency
 -- @treturn array Shifted impulse response taps
@@ -29,7 +35,8 @@ end
 ---
 -- Generate the shifted, truncated coefficients of an ideal high-pass filter.
 --
--- @local
+-- @internal
+-- @function fir_highpass
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam number cutoff Normalized cutoff frequency
 -- @treturn array Shifted impulse response taps
@@ -52,7 +59,8 @@ end
 ---
 -- Generate the shifted, truncated coefficients of an ideal band-pass filter.
 --
--- @local
+-- @internal
+-- @function fir_bandpass
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam {number,number} cutoffs Normalized cutoff frequencies
 -- @treturn array Shifted impulse response taps
@@ -76,7 +84,8 @@ end
 ---
 -- Generate the shifted, truncated coefficients of an ideal band-stop filter.
 --
--- @local
+-- @internal
+-- @function fir_bandstop
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam {number,number} cutoffs Normalized cutoff frequencies
 -- @treturn array Shifted impulse response taps
@@ -103,7 +112,8 @@ end
 ---
 -- Apply window to and normalize magnitude of finite impulse response taps.
 --
--- @local
+-- @internal
+-- @function firwin
 -- @tparam array h Impulse response taps
 -- @tparam[opt='hamming'] string window_type Window function type
 -- @tparam number scale_freq Normalized frequency to scale to unity magnitude
@@ -133,7 +143,8 @@ end
 ---
 -- Generate FIR low-pass filter taps by the window design method.
 --
--- @local
+-- @internal
+-- @function firwin_lowpass
 -- @tparam int num_taps Number of taps
 -- @tparam number cutoff Normalized cutoff frequency
 -- @tparam[opt='hamming'] string window_type Window function type
@@ -148,7 +159,8 @@ end
 ---
 -- Generate FIR high-pass filter taps by the window design method.
 --
--- @local
+-- @internal
+-- @function firwin_highpass
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam number cutoff Normalized cutoff frequency
 -- @tparam[opt='hamming'] string window_type Window function type
@@ -163,7 +175,8 @@ end
 ---
 -- Generate FIR band-pass filter taps by the window design method.
 --
--- @local
+-- @internal
+-- @function firwin_bandpass
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam {number,number} cutoffs Normalized cutoff frequencies
 -- @tparam[opt='hamming'] string window_type Window function type
@@ -178,7 +191,8 @@ end
 ---
 -- Generate FIR band-stop filter taps by the window design method.
 --
--- @local
+-- @internal
+-- @function firwin_bandstop
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam {number,number} cutoffs Normalized cutoff frequencies
 -- @tparam[opt='hamming'] string window_type Window function type
@@ -196,7 +210,8 @@ end
 -- Apply window to and normalize magnitude of complex finite impulse response
 -- taps.
 --
--- @local
+-- @internal
+-- @function complex_firwin
 -- @tparam array h Complex impulse response taps
 -- @tparam number scale_freq Normalized center frequency of filter
 -- @tparam[opt='hamming'] string window_type Window function type
@@ -236,7 +251,8 @@ end
 ---
 -- Generate FIR complex band-pass filter taps by the window design method.
 --
--- @local
+-- @internal
+-- @function firwin_complex_bandpass
 -- @tparam int num_taps Number of taps
 -- @tparam {number,number} cutoffs Normalized cutoff frequencies, can be
 --                                 positive or negative
@@ -252,7 +268,8 @@ end
 ---
 -- Generate FIR complex band-stop filter taps by the window design method.
 --
--- @local
+-- @internal
+-- @function firwin_complex_bandstop
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam {number,number} cutoffs Normalized cutoff frequencies, can be
 --                                 positive or negative
@@ -274,7 +291,8 @@ end
 -- Generate an FIR approximation of a root-raised cosine filter, normalized to
 -- unity gain at DC.
 --
--- @local
+-- @internal
+-- @function fir_root_raised_cosine
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam number sample_rate Sample rate in Hz
 -- @tparam number beta Roll-off factor
@@ -324,7 +342,8 @@ end
 ---
 -- Generate a windowed FIR approximation of the discrete Hilbert transform.
 --
--- @local
+-- @internal
+-- @function fir_hilbert_transform
 -- @tparam int num_taps Number of taps, must be odd
 -- @tparam[opt='hamming'] string window_type Window function type
 -- @treturn array Filter taps

radio/blocks/signal/firfilter.lua

@@ -2,16 +2,17 @@
 -- Filter a complex or real valued signal with an FIR filter.
 --
 -- $$ y[n] = (x * h)[n] $$
+--
 -- $$ y[n] = b_0 x[n] + b_1 x[n-1] + ... + b_N x[n-N] $$
 --
 -- @category Filtering
 -- @block FIRFilterBlock
 -- @tparam array|vector taps Real-valued taps specified with a number array or
 --                           a Float32 vector, or complex-valued taps specified
 --                           with a ComplexFloat32 vector
--- @tparam[opt] bool use_fft Use FFT overlap-save convolution. Defaults to true
---                           when acceleration is available and taps length is
---                           greater than 16
+-- @tparam[opt=true] bool use_fft Use FFT overlap-save convolution. Defaults to true
+--                                when acceleration is available and taps length is
+--                                greater than 16
 --
 -- @signature in:ComplexFloat32 > out:ComplexFloat32
 -- @signature in:Float32 > out:Float32

radio/blocks/signal/iirfilter.lua

@@ -2,6 +2,7 @@
 -- Filter a complex or real valued signal with an IIR filter.
 --
 -- $$ y[n] = (x * h)[n] $$
+--
 -- $$ \begin{align} y[n] = &\frac{1}{a_0}(b_0 x[n] + b_1 x[n-1] + ... + b_N x[n-N] \\ - &a_1 y[n-1] - a_2 y[n-2] - ... - a_M x[n-M])\end{align} $$
 --
 -- @category Filtering

radio/blocks/signal/singlepolehighpassfilter.lua

@@ -3,7 +3,9 @@
 -- filter.
 --
 -- $$ H(s) = \frac{\tau s}{\tau s + 1} $$
+--
 -- $$ H(z) = \frac{2\tau f_s}{1 + 2\tau f_s} \frac{1 - z^{-1}}{1 + (\frac{1 - 2\tau f_s}{1 + 2\tau f_s}) z^{-1}} $$
+--
 -- $$ y[n] = \frac{2\tau f_s}{1 + 2\tau f_s} \; x[n] + \frac{2\tau f_s}{1 + 2\tau f_s} \; x[n-1] - \frac{1 - 2\tau f_s}{1 + 2\tau f_s} \; y[n-1] $$
 --
 -- @category Filtering

radio/blocks/signal/singlepolelowpassfilter.lua

@@ -3,7 +3,9 @@
 -- filter.
 --
 -- $$ H(s) = \frac{1}{\tau s + 1} $$
+--
 -- $$ H(z) = \frac{1}{1 + 2\tau f_s} \frac{1 + z^{-1}}{1 + (\frac{1 - 2\tau f_s}{1 + 2\tau f_s}) z^{-1}} $$
+--
 -- $$ y[n] = \frac{1}{1 + 2\tau f_s} \; x[n] + \frac{1}{1 + 2\tau f_s} \; x[n-1] - \frac{1 - 2\tau f_s}{1 + 2\tau f_s} \; y[n-1] $$
 --
 -- @category Filtering

radio/blocks/signal/spectrum_utils.lua

@@ -1,3 +1,8 @@
+---
+-- DFT, IDFT, PSD, and fftshift implementations.
+--
+-- @module radio.blocks.signal.spectrum_utils
+
 local ffi = require('ffi')
 local math = require('math')
 
@@ -13,8 +18,8 @@ local window_utils = require('radio.blocks.signal.window_utils')
 ---
 -- Discrete Fourier Transform class.
 --
--- @local
--- @type DFT
+-- @internal
+-- @class DFT
 -- @tparam vector input_samples ComplexFloat32 or Float32 vector of input samples
 -- @tparam vector output_samples ComplexFloat32 vector of output transformed samples
 local DFT = class.factory()
@@ -54,7 +59,7 @@ end
 ---
 -- Compute the discrete fourier transform.
 --
--- @local
+-- @internal
 -- @function DFT:compute
 
 --------------------------------------------------------------------------------
@@ -258,8 +263,8 @@ end
 ---
 -- Inverse Discrete Fourier Transform class.
 --
--- @local
--- @type IDFT
+-- @internal
+-- @class IDFT
 -- @tparam vector input_samples ComplexFloat32 vector of input DFT samples
 -- @tparam vector output_samples ComplexFloat32 or Float32 vector of output samples
 local IDFT = class.factory()
@@ -299,8 +304,8 @@ end
 ---
 -- Compute the inverse discrete fourier transform.
 --
--- @local
--- @function DFT:compute
+-- @internal
+-- @function IDFT:compute
 
 --------------------------------------------------------------------------------
 -- IDFT implementations
@@ -529,8 +534,8 @@ end
 ---
 -- Power Spectral Density class.
 --
--- @local
--- @type PSD
+-- @internal
+-- @class PSD
 -- @tparam vector input_samples ComplexFloat32 or Float32 vector of input samples
 -- @tparam vector output_samples Float32 vector of output power spectral density samples
 -- @tparam[opt='hamming'] string window_type Window type
@@ -580,8 +585,8 @@ end
 ---
 -- Compute the power spectral density.
 --
--- @local
--- @function DFT:compute
+-- @internal
+-- @function PSD:compute
 
 --------------------------------------------------------------------------------
 -- PSD implementations
@@ -665,7 +670,8 @@ end
 ---
 -- Shift frequency components into negative, zero, positive frequency order.
 --
--- @local
+-- @internal
+-- @function fftshift
 -- @tparam vector samples ComplexFloat32 or Float32 vector of samples
 local function fftshift(samples)
     local offset = samples.length/2

radio/blocks/signal/window_utils.lua

@@ -1,3 +1,8 @@
+---
+-- Window generation function.
+--
+-- @module radio.blocks.signal.window_utils
+
 local math = require('math')
 
 -- Window functions.
@@ -24,7 +29,8 @@ local window_functions = {
 ---
 -- Generate a window.
 --
--- @local
+-- @internal
+-- @function window
 -- @tparam int M Window length
 -- @tparam string window_type Window function, choice of "rectangular",
 --                            "hamming", "hanning", "bartlett", "blackman".