♻️ refactor: Improve docstrings and simplify some trivial generators.

Author: make-github-pseudonymous-again

src/_bitreversal.js

@@ -5,7 +5,7 @@
  * power of <code>2</code>.
  *
  * @param {Array} array The array to fill.
- * @param {Number} n The size of the permutation, must be a power of 2.
+ * @param {number} n The size of the permutation, must be a power of 2.
  */
 export function _bitreversal(array, n) {
 	let i = 1;

src/_compose.js

@@ -4,7 +4,7 @@
  *
  * @param {Array} sigma The first input permutation.
  * @param {Array} tau The second input permutation.
- * @returns {Iterator} An iterator over the items of the resulting permutation.
+ * @returns {IterableIterator} An iterator over the items of the resulting permutation.
  */
 export function* _compose(sigma, tau) {
 	for (const t of tau) yield sigma[t];

src/_copy.js

@@ -2,7 +2,7 @@
  * Copy an input permutation to an output array.
  *
  * @param {Array} sigma The input permutation.
- * @param {Number} n The size of the input permutation to copy.
+ * @param {number} n The size of the input permutation to copy.
  * @param {Array} tau The output array.
  */
 export function _copy(sigma, n, tau) {

src/_cycles.js

@@ -14,7 +14,7 @@
  *
  * @param {Array} sigma The input permutation.
  * @param {Array} used The helper array.
- * @returns {Iterator} The cycles <code>[a, [b, c, ...]]</code> for sigma.
+ * @returns {IterableIterator} The cycles <code>[a, [b, c, ...]]</code> for sigma.
  */
 export function* _cycles(sigma, used) {
 	for (const s of sigma) {

src/_identity.js

@@ -3,7 +3,7 @@
  * elements.
  *
  * @param {Array} sigma The input array.
- * @param {Number} n The size to use for the permutation.
+ * @param {number} n The size to use for the permutation.
  */
 export function _identity(sigma, n) {
 	for (let i = 0; i < n; ++i) sigma[i] = i;

src/_invert.js

@@ -6,7 +6,7 @@
  * API.
  *
  * @param {Array} sigma The input permutation.
- * @param {Number} n The size of the input permutation.
+ * @param {number} n The size of the input permutation.
  * @param {Array} tau The array where to put the inverse of the input permutation.
  */
 export function _invert(sigma, n, tau) {

src/_itranspositions.js

@@ -6,7 +6,7 @@
  *
  * @param {Array} sigma Input permutation.
  * @param {Array} used Helper array.
- * @return {Iterator} Iterator over the transpositions.
+ * @return {IterableIterator} Iterator over the transpositions.
  */
 export function* _itranspositions(sigma, used) {
 	for (const s of sigma) {

src/_next.js

@@ -7,7 +7,7 @@ import {_reverse} from './_reverse.js';
  * input permutation remains untouched.
  *
  * @param {Array} sigma The input permutation (modified in-place).
- * @param {Number} n The size of the input permutation.
+ * @param {number} n The size of the input permutation.
  * @returns {Boolean} Whether the input permutation is
  * __NOT__ the last for its elements.
  */

src/_permutations.js

@@ -5,8 +5,8 @@ import {_next} from './_next.js';
  * permutation.
  *
  * @param {Array} sigma The starting permutation.
- * @param {Number} n The size of the permutation.
- * @returns {Iterator} Iterator over all permutations between the starting one
+ * @param {number} n The size of the permutation.
+ * @returns {IterableIterator} Iterator over all permutations between the starting one
  * and the last permutation on its elements.
  */
 export function* _permutations(sigma, n) {

src/_reverse.js

@@ -5,8 +5,8 @@ import {_transpose} from './_transpose.js';
  * (include) to input index <code>j</code> (excluded).
  *
  * @param {Array} sigma The input permutation to reverse (modified in-place).
- * @param {Number} i The left bound (included).
- * @param {Number} j The right bound (excluded).
+ * @param {number} i The left bound (included).
+ * @param {number} j The right bound (excluded).
  */
 export function _reverse(sigma, i, j) {
 	while (i < --j) _transpose(i++, j, sigma);

src/_transpose.js

@@ -2,8 +2,8 @@
  * Transpose elements of input index <code>a</code> and <code>b</code> in the
  * input permutation.
  *
- * @param {Number} a The first input index.
- * @param {Number} b The second input index.
+ * @param {number} a The first input index.
+ * @param {number} b The second input index.
  * @param {Array} sigma The input permutation.
  */
 export function _transpose(a, b, sigma) {

src/_transposition.js

@@ -3,8 +3,8 @@
  * Transposes <code>a</code> with <code>b</code> in <code>sigma</code> provided
  * <code>sigma[a] === a</code> and <code>sigma[b] === b</code>.
  *
- * @param {Number} a First index.
- * @param {Number} b Second index.
+ * @param {number} a First index.
+ * @param {number} b Second index.
  * @param {Array} sigma Input permutation.
  */
 export function _transposition(a, b, sigma) {

src/_transpositions.js

@@ -2,8 +2,8 @@
  * Computes the transposition decomposition of some permutation given its cycle
  * decomposition.
  *
- * @param {Array} cycles The cycle decomposition of some permutation.
- * @returns {Iterator} The transposition decomposition of the permutation
+ * @param {Iterable} cycles The cycle decomposition of some permutation.
+ * @returns {IterableIterator} The transposition decomposition of the permutation
  * defined by the input cycles.
  */
 export function* _transpositions(cycles) {

src/_used.js

@@ -5,7 +5,7 @@
  * example, for computing the cycle decomposition of an input permutation (see
  * {@link _cycles}, {@link cycles}).
  *
- * @param {Number} n The given size.
+ * @param {number} n The given size.
  * @param {Array} array The input array.
  */
 export function _used(n, array) {

src/apply.js

@@ -5,7 +5,7 @@ import {_apply} from './_apply.js';
  * Apply a given sequence (in the given order) of transpositions (given as
  * index tuples) to the identity permutation over input <code>n</code> elements.
  *
- * @param {Number} n The size of the identity permutation to apply the transpositions
+ * @param {number} n The size of the identity permutation to apply the transpositions
  * to.
  * @param {Iterable} transpositions The given transpositions to apply.
  * @returns {Array} The resulting permutation.

src/bitreversal.js

@@ -6,7 +6,7 @@ import {_bitreversal} from './_bitreversal.js';
  * input <code>n</code> items. Note that <code>n</code> MUST be a power of
  * <code>2</code>.
  *
- * @param {Number} n The size of the permutation, must be a power of
+ * @param {number} n The size of the permutation, must be a power of
  * <code>2</code>.
  * @returns {Array} The bitreversal permutation of size <code>n</code>.
  */

src/cycles.js

@@ -7,8 +7,6 @@ import {used} from './used.js';
  * See {@link _cycles} for implementation.
  *
  * @param {Array} sigma The input permutation.
- * @returns {Iterator} The cycles <code>[a, [b, c, ...]]</code> for sigma.
+ * @returns {IterableIterator} The cycles <code>[a, [b, c, ...]]</code> for sigma.
  */
-export function* cycles(sigma) {
-	yield* _cycles(sigma, used(sigma.length));
-}
+export const cycles = (sigma) => _cycles(sigma, used(sigma.length));

src/identity.js

@@ -4,7 +4,7 @@ import {_identity} from './_identity.js';
 /**
  * Returns the identity permutation of a given size.
  *
- * @param {Number} n The size of the permutation to return.
+ * @param {number} n The size of the permutation to return.
  * @returns {Array} The identity permutation on <code>n</code> elements.
  */
 export function identity(n) {

src/itranspositions.js

@@ -10,8 +10,7 @@ import {used} from './used.js';
  * const invert = sigma => apply( sigma.length , itranspositions( sigma ) ) ;
  *
  * @param {Array} sigma Input permutation.
- * @return {Iterator} Iterator over the transpositions.
+ * @return {IterableIterator} Iterator over the transpositions.
  */
-export function* itranspositions(sigma) {
-	yield* _itranspositions(sigma, used(sigma.length));
-}
+export const itranspositions = (sigma) =>
+	_itranspositions(sigma, used(sigma.length));

src/permutation.js

@@ -1,7 +1,7 @@
 /**
  * Allocates a new permutation of given input size.
  *
- * @param {Number} n The size of the permutation to allocate.
+ * @param {number} n The size of the permutation to allocate.
  * @returns {Array} The allocated permutation.
  */
 export function permutation(n) {

src/permutations.js

@@ -5,8 +5,8 @@ import {copy} from './copy.js';
 /**
  * Generate all permutations on <code>n</code> elements.
  *
- * @param {Number} n The size of the permutations to generate.
- * @returns {Iterator} Iterator that yields all permutations on <code>n</code>
+ * @param {number} n The size of the permutations to generate.
+ * @returns {IterableIterator} Iterator that yields all permutations on <code>n</code>
  * elements.
  */
 export function* permutations(n) {

src/transpose.js

@@ -6,8 +6,8 @@ import {_transpose} from './_transpose.js';
  * then returns the result.
  *
  * @param {Array} sigma The input permutation.
- * @param {Number} a The first index of the transpose.
- * @param {Number} b The second index of the transpose.
+ * @param {number} a The first index of the transpose.
+ * @param {number} b The second index of the transpose.
  * @returns {Array} The result.
  */
 export function transpose(sigma, a, b) {

src/transposition.js

@@ -5,9 +5,9 @@ import {_transposition} from './_transposition.js';
  * Outputs the permutation on input <code>n</code> numbers that only transposes
  * two input elements <code>a</code> and <code>b</code>.
  *
- * @param {Number} n The size of the permutation to output.
- * @param {Number} a The first index to swap.
- * @param {Number} b The second index to swap.
+ * @param {number} n The size of the permutation to output.
+ * @param {number} a The first index to swap.
+ * @param {number} b The second index to swap.
  * @returns {undefined}
  */
 export function transposition(n, a, b) {

src/transpositions.js

@@ -1,14 +1,11 @@
 import {_transpositions} from './_transpositions.js';
 import {cycles} from './cycles.js';
-import {used} from './used.js';
 
 /**
  * Computes the transposition decomposition of the input permutation as an
  * Iterator.
  *
  * @param {Array} sigma The input permutation.
- * @returns {Iterator} The transposition decomposition of <code>sigma</code>.
+ * @returns {IterableIterator} The transposition decomposition of <code>sigma</code>.
  */
-export function* transpositions(sigma) {
-	yield* _transpositions(cycles(sigma, used(sigma.length)));
-}
+export const transpositions = (sigma) => _transpositions(cycles(sigma));

src/used.js

@@ -3,7 +3,7 @@ import {_used} from './_used.js';
 /**
  * Generates an helper array of given size (used in {@link _cycle}, {@link cycle}).
  *
- * @param {Number} n The given size.
+ * @param {number} n The given size.
  * @returns {Array} The helper array of prescribed size.
  */
 export function used(n) {