docs: add comment and TODOs

---
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/cosqb.js

@@ -82,7 +82,7 @@ var TSQRT2 = 2.0 * SQRT_TWO;
 * @param {number} wptr - starting index for `wsave`
 * @returns {void}
 */
-function cosqb( n, x, xptr, wsave, wptr ) {
+function cosqb( n, x, xptr, wsave, wptr ) { // TODO: consider moving to a separate package `fft/base/fftpack/cosqb` after this package has been refactored
 	var x1;
 
 	wptr -= 1;

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

@@ -76,7 +76,7 @@ var cosqf1 = require( './cosqf1.js' );
 * @param {number} wptr - starting index for `wsave`
 * @returns {void}
 */
-function cosqf( n, x, xptr, wsave, wptr ) {
+function cosqf( n, x, xptr, wsave, wptr ) { // TODO: consider moving to a separate package `fft/base/fftpack/cosqf` after this package has been refactored
 	var tsqx;
 
 	wptr -= 1;

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

@@ -75,7 +75,7 @@ var rffti = require( './rffti.js' );
 * @param {number} wptr - starting index for `wsave`
 * @returns {void}
 */
-function cosqi( n, wsave, wptr ) {
+function cosqi( n, wsave, wptr ) { // TODO: consider moving to a separate package `fft/base/fftpack/cosqi` after this package has been refactored
 	var fk;
 	var dt;
 	var k;

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

@@ -75,7 +75,7 @@ var rfftf = require( './rfftf.js' );
 * @param {number} wptr - starting index for wsave
 * @returns {void}
 */
-function cost( n, x, xptr, wsave, wptr ) {
+function cost( n, x, xptr, wsave, wptr ) { // TODO: consider moving to a separate package `fft/base/fftpack/cost` after this package has been refactored
 	var x1p3;
 	var xim2;
 	var modn;

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

@@ -75,7 +75,7 @@ var rffti = require( './rffti.js' );
 * @param {number} wptr - starting index for `wsave`
 * @returns {void}
 */
-function costi( n, wsave, wptr ) {
+function costi( n, wsave, wptr ) { // TODO: consider moving to a separate package `fft/base/fftpack/costi` after this package has been refactored
 	var nm1;
 	var np1;
 	var ns2;

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

@@ -66,14 +66,14 @@ var floor = require( '@stdlib/math/base/special/floor' );
 // MAIN //
 
 /**
-* Factorizes a sequence length into its prime factors.
+* Factorizes a sequence length into a product of integers.
 *
 * ## Notes
 *
 * -   Factorization results are stored in the input array as follows:
 *
 *     ```text
-*     [ sequence_length | number_of_factors | prime_factors | unused_storage ]
+*     [ sequence_length | number_of_factors | integer_factors | unused_storage ]
 *     ```
 *
 * -   The function mutates the input array.
@@ -96,7 +96,7 @@ var floor = require( '@stdlib/math/base/special/floor' );
 * // Initialize an array for storing factorization results:
 * var factors = [ 0, 0, 0, 0, 0, 0, 0 ];
 *
-* // Factorize the sequence length into its prime factors:
+* // Factorize the sequence length into a product of integers:
 * var numFactors = decompose( N, initial, factors, 1, 0 );
 * // returns 5
 *
@@ -113,14 +113,14 @@ var floor = require( '@stdlib/math/base/special/floor' );
 * // Initialize an array for storing factorization results:
 * var factors = [ 0, 0, 0, 0 ];
 *
-* // Factorize the sequence length into its prime factors:
+* // Factorize the sequence length into its a product of integers:
 * var numFactors = decompose( N, initial, factors, 1, 0 );
 * // returns 2
 *
 * var f = factors.slice();
 * // returns [ 8, 2, 2, 4 ]
 */
-function decompose( N, initial, out, stride, offset ) {
+function decompose( N, initial, out, stride, offset ) { // TODO: consider moving to a separate utility package
 	var divisor;
 	var ntrials;
 	var nl;

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

@@ -35,7 +35,7 @@ var strided2array = require( '@stdlib/array/base/from-strided' );
 * @param {NonNegativeInteger} offsetW - starting index for `workspace`
 * @returns {void}
 */
-function printWorkspace( N, workspace, strideW, offsetW ) {
+function printWorkspace( N, workspace, strideW, offsetW ) { // FIXME: remove this file and function once we've clean-up this package
 	var offsetT;
 	var offsetF;
 	var tmp;

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

@@ -117,9 +117,36 @@ function iptr( i, j, k, M, stride, offset ) {
 *
 * ## Notes
 *
-* When writing to an output array stored in linear memory, we can reinterpret the array as a three-dimensional logical view containing `L` independent sub-sequences having two "columns" corresponding to the real and imaginary parts of a folded complex vector and where each "column" has `M` elements.
+* When writing to an output array stored in linear memory, we can reinterpret the array as a three-dimensional logical view containing `L` independent sub-sequences having two "rows" corresponding to the two parts of the butterfly (`even + odd` and `even - odd`, respectively) and where each "row" has `M*L` elements.
 *
-* Accordingly, the following is a logical view of an input array (zero-based indexing) which contains `L = 3` transforms and in which each "column" sub-sequence has length `M = 4`:
+* Accordingly, the following is a logical view of an input array (zero-based indexing) which contains `L = 3` transforms and in which each sub-sequence has length `M = 4`:
+*
+* ```text
+*                  │            k = 0                      k = 1                      k = 2
+*                  │ ───────────────────────────────────────────────────────────────────────────────→ k
+* j = 0 (even+odd) │  out(0,0,0) ... out(3,0,0)  out(0,1,0) ... out(3,1,0)  out(0,2,0) ... out(3,2,0)
+*                  │
+* j = 1 (even-odd) │  out(0,0,1) ... out(3,0,1)  out(0,1,1) ... out(3,1,1)  out(0,2,1) ... out(3,2,1)
+*                  └────────────────────────────────────────────────────────────────────────────────→ i
+*                         ↑              ↑           ↑              ↑           ↑              ↑
+*                       i = 0           M-1          0             M-1          0             M-1
+* ```
+*
+* In the above,
+*
+* -   `i` is the fastest varying index, which walks within one short sub-sequence corresponding to either the `even + odd` or `even - odd` part of the butterfly.
+* -   `j` selects between the `even + odd` and `even - odd` part of the butterfly.
+* -   `k` specifies the index of one of the `L` independent transforms we are processing.
+*
+* In linear memory, the three-dimensional logical view is arranged as follows:
+*
+* ```text
+* | out(0,0,0)...out(3,0,0) ... out(0,2,0)...out(3,2,0) | out(0,0,1)...out(3,0,1) ... out(0,2,1)...out(3,2,1) |
+* ```
+*
+* As may be observed, when resolving an index in the output array, the `j` and `k` dimensions are swapped. This stems from `radb2` being only one stage in a multi-stage driver which alternates between using `ch` and `out` as workspace buffers. After each stage, the next stage reads what the previous stage wrote.
+*
+* Each stage expects a transpose, and, in order to avoid explicit transposition between the stages, we swap the last two logical dimensions while still maintaining cache locality within the inner loop logical dimension, as indexed by `i`.
 *
 * @private
 * @param {NonNegativeInteger} i - index of an element within a sub-sequence
@@ -204,9 +231,6 @@ function radb2( M, L, cc, oc, out, oo, twiddles, ot ) { // FIXME: support stride
 			for ( i = 2; i < M; i += 2 ) {
 				ic = MP1 - i;
 
-				it1 = i - 1 + ot;
-				it2 = i + ot;
-
 				ip1 = iptr( i, 0, k, M, sc, oc );
 				ip2 = iptr( ic-1, 1, k, M, sc, oc );
 				tr2 = cc[ ip1 ] - cc[ ip2 ];
@@ -221,6 +245,9 @@ function radb2( M, L, cc, oc, out, oo, twiddles, ot ) { // FIXME: support stride
 				io = optr( i+1, k, 0, L, M, so, oo );
 				out[ io ] = cc[ ip1 ] - cc[ ip2 ];
 
+				it1 = i - 1 + ot;
+				it2 = i + ot;
+
 				io = optr( i, k, 1, L, M, so, oo );
 				out[ io ] = ( twiddles[ it1 ] * tr2 ) - ( twiddles[ it2 ] * ti2 );
 

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

@@ -75,7 +75,7 @@ var cosqb = require( './cosqb.js' );
 * @param {number} wptr - starting index for `wsave`
 * @returns {void}
 */
-function sinqb( n, x, xptr, wsave, wptr ) {
+function sinqb( n, x, xptr, wsave, wptr ) { // TODO: consider moving to a separate package `fft/base/fftpack/sinqb` after this package has been refactored
 	var xhold;
 	var ns2;
 	var kc;

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

@@ -75,7 +75,7 @@ var cosqb = require( './cosqb.js' );
 * @param {number} wptr - starting index for `wsave`
 * @returns {void}
 */
-function sinqf( n, x, xptr, wsave, wptr ) {
+function sinqf( n, x, xptr, wsave, wptr ) { // TODO: consider moving to a separate package `fft/base/fftpack/sinqf` after this package has been refactored
 	var xhold;
 	var ns2;
 	var kc;