chore: add docs and clean-up

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: kgryte

lib/node_modules/@stdlib/fft/base/fftpack/lib/cc_ref.js

@@ -70,6 +70,10 @@
 * @param {NonNegativeInteger} ip - number of sub-steps or prime factors in the FFT
 * @param {NonNegativeInteger} ido - dimension order
 * @returns {NonNegativeInteger} computed index
+*
+* @example
+* var out = ccRef( 3, 2, 1, 2, 2 );
+* // returns 11
 */
 function ccRef( a1, a2, a3, ip, ido ) {
 	return ( ( (a3*ip)+a2 ) * ido ) + a1;

lib/node_modules/@stdlib/fft/base/fftpack/lib/cfftb.js

@@ -66,28 +66,64 @@ var cfftb1 = require( './cfftb1.js' );
 // MAIN //
 
 /**
-* Performs the complex backward Fast Fourier Transform.
+* Performs the backward complex Fourier transform (i.e., the Fourier synthesis).
 *
-* @param {number} n - length of the sequence to transform
-* @param {Float64Array} c - input array containing sequence to be transformed
-* @param {number} cptr - starting index for c
-* @param {Float64Array} wsave - working array containing precomputed values
-* @param {number} wptr - starting index for wsave
+* ## Notes
+*
+* -   This function computes a complex periodic sequence from its Fourier coefficients.
+*
+* -   Invoking `cfftf` prior to invoking this function will multiply an input sequence by `N`.
+*
+* -   Prior to invoking this function, `wsave` must be initialized by calling `cffti(N, wsave)`.
+*
+* -   This function is more efficient when `N` is the product of small prime numbers.
+*
+* -   A provided workspace array must have at least `4N+15` elements.
+*
+* -   Different workspace arrays must be used for each different value of `N`.
+*
+* -   The workspace array does **not** require re-initialization between subsequent transforms as long as `N` remains the same. Hence, subsequent transforms can be performed faster than the first by avoiding repeated initialization.
+*
+* -   The same workspace array can be used by both `cfftf` and `cfftb`.
+*
+* -   The initialization calculations stored in a workspace must **not** be destroyed between calls of `cfftf` and `cfftb`.
+*
+* -   This function mutates the input array `c`. For `j = 0, ..., N-1`,
+*
+*     ```tex
+*     c_j = \sum_{k=0}^{N-1} c_k \cdot e^{\frac{2\pi}{N} \cdot ijk}
+*     ```
+*
+*     where `i = sqrt(-1)`.
+*
+* @param {NonNegativeInteger} N - length of the sequence to transform
+* @param {Float64Array} c - input array containing the sequence to be transformed
+* @param {NonNegativeInteger} offsetC - starting index for `c`
+* @param {Float64Array} wsave - workspace array containing pre-computed values
+* @param {NonNegativeInteger} offsetW - starting index for `wsave`
 * @returns {void}
+*
+* @example
+* // TODO
 */
-function cfftb( n, c, cptr, wsave, wptr ) {
-	var iw1;
-	var iw2;
+function cfftb( N, c, offsetC, wsave, offsetW ) {
+	var offsetT;
+	var offsetF;
 
-	wptr -= 1;
-	cptr -= 1;
-
-	if ( n === 1 ) {
+	if ( N <= 1 ) {
 		return;
 	}
-	iw1 = ( 2 * n ) + 1;
-	iw2 = iw1 + ( 2 * n );
-	cfftb1( n, c, cptr + 1, wsave, wptr + 1, wsave, wptr + iw1, wsave, wptr + iw2 ); // eslint-disable-line max-len
+	/*
+	* The workspace array is divided into three sections:
+	*
+	*     [ intermediate_results | twiddle_factors | factorization_info ]
+	*
+	* The first two sections each contain `2*N` elements.
+	*/
+	offsetT = N * 2;       // index offset for twiddle factors
+	offsetF = offsetT * 2; // index offset for factorization info
+
+	cfftb1( N, c, offsetC, wsave, offsetW, wsave, offsetW+offsetT, wsave, offsetW+offsetF ); // eslint-disable-line max-len
 }
 
 

lib/node_modules/@stdlib/fft/base/fftpack/lib/cfftb1.js

@@ -72,7 +72,7 @@ var passfb = require( './passfb.js' );
 // MAIN //
 
 /**
-* Performs the complex backward Fast Fourier Transform.
+* Performs the backward complex Fourier transform (i.e., the Fourier synthesis).
 *
 * @private
 * @param {number} n - length of the sequence to transform
@@ -103,13 +103,12 @@ function cfftb1( n, c, cOffset, ch, chOffset, wa, waOffset, ifac, ifacOffset ) {
 	var iw;
 	var i;
 
-	// Function Body:
-	nf = ifac[ ifacOffset + 1 ];
+	nf = ifac[ ifacOffset+1 ];
 	na = 0;
 	l1 = 1;
 	iw = 0;
 	for ( k1 = 1; k1 <= nf; k1++ ) {
-		ip = ifac[ ifacOffset + k1 + 1 ];
+		ip = ifac[ ifacOffset+k1+1 ];
 		l2 = ip * l1;
 		ido = n / l2;
 		idot = ido + ido;
@@ -118,30 +117,30 @@ function cfftb1( n, c, cOffset, ch, chOffset, wa, waOffset, ifac, ifacOffset ) {
 		case 4:
 			ix2 = iw + idot;
 			ix3 = ix2 + idot;
-			passb4( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw + waOffset, wa, ix2 + waOffset, wa, ix3 + waOffset );
+			passb4( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw+waOffset, wa, ix2+waOffset, wa, ix3+waOffset );
 			na = 1 - na;
 			break;
 		case 2:
-			passb2( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw + waOffset );
+			passb2( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw+waOffset );
 			na = 1 - na;
 			break;
 		case 3:
 			ix2 = iw + idot;
-			passb3( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw + waOffset, wa, ix2 + waOffset );
+			passb3( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw+waOffset, wa, ix2+waOffset );
 			na = 1 - na;
 			break;
 		case 5:
 			ix2 = iw + idot;
 			ix3 = ix2 + idot;
 			ix4 = ix3 + idot;
-			passfb5( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw + waOffset, wa, ix2 + waOffset, wa, ix3 + waOffset, wa, ix4 + waOffset, 1 );
+			passfb5( idot, l1, ( na ) ? ch : c, ( na ) ? chOffset : cOffset, ( na ) ? c : ch, ( na ) ? cOffset : chOffset, wa, iw+waOffset, wa, ix2+waOffset, wa, ix3+waOffset, wa, ix4+waOffset, 1 );
 			na = 1 - na;
 			break;
 		default:
 			if ( na === 0 ) {
-				passfb( nac, idot, ip, l1, idl1, c, cOffset, c, cOffset, c, cOffset, ch, chOffset, ch, chOffset, wa, iw + waOffset, 1 );
+				passfb( nac, idot, ip, l1, idl1, c, cOffset, c, cOffset, c, cOffset, ch, chOffset, ch, chOffset, wa, iw+waOffset, 1 );
 			} else {
-				passfb( nac, idot, ip, l1, idl1, ch, chOffset, ch, chOffset, ch, chOffset, c, cOffset, c, cOffset, wa, iw + waOffset, 1 );
+				passfb( nac, idot, ip, l1, idl1, ch, chOffset, ch, chOffset, ch, chOffset, c, cOffset, c, cOffset, wa, iw+waOffset, 1 );
 			}
 			if ( nac !== 0 ) {
 				na = 1 - na;
@@ -154,8 +153,8 @@ function cfftb1( n, c, cOffset, ch, chOffset, wa, waOffset, ifac, ifacOffset ) {
 	if ( na === 0 ) {
 		return;
 	}
-	for ( i = 0; i < ( 2 * n ); i++ ) {
-		c[ i + cOffset ] = ch[ i + chOffset ];
+	for ( i = 0; i < n*2; i++ ) {
+		c[ i+cOffset ] = ch[ i+chOffset ];
 	}
 }