add docs

Author: make-github-pseudonymous-again

src/_apply.js

@@ -1,12 +1,15 @@
 import { _transpose } from './_transpose' ;
 
+/**
+ * Applies a given sequence (in the given order) of transpositions (given as
+ * index tuples) to a given permutation. The permutation is modified in place.
+ *
+ * @param transpositions The given transpositions to apply.
+ * @param sigma The permutation to apply the transpositions to.
+ */
 export function _apply ( transpositions , sigma ) {
 
-	for ( const [ s , t ] of transpositions ) {
-
-		_transpose( s , t , sigma ) ;
-
-	}
+	for ( const [ s , t ] of transpositions ) _transpose( s , t , sigma ) ;
 
 }
 

src/_bitreversal.js

@@ -1,4 +1,13 @@
 
+/**
+ * Fills an input array with the bitreversal permutation for input
+ * <code>n</code> items. The array is filled starting at index <code>0</code>
+ * and ending at index <code>n-1</code>. Note that <code>n</code> MUST be a
+ * 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.
+ */
 export function _bitreversal ( array , n ) {
 
 	let i = 1 ;

src/_compose.js

@@ -1,4 +1,12 @@
 
+/**
+ * Compose two input permutations. The resulting permutation is output as an
+ * iterator of indices instead of an array of indices.
+ *
+ * @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.
+ */
 export function* _compose ( sigma , tau ) {
 
 	for ( const t of tau ) yield sigma[t] ;

src/_copy.js

@@ -1,11 +1,14 @@
 
+/**
+ * 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 {Array} tau The output array.
+ */
 export function _copy ( sigma , n , tau ) {
 
-	for ( let i = 0 ; i < n ; ++i ) {
-
-		tau[i] = sigma[i] ;
-
-	}
+	for ( let i = 0 ; i < n ; ++i ) tau[i] = sigma[i] ;
 
 }
 

src/_cycles.js

@@ -1,4 +1,20 @@
 
+/**
+ * Computes a {@link https://en.wikipedia.org/wiki/Permutation#Cycle_notation
+ * cycle decomposition} of an input permutation. This algorithm is
+ * deterministic; the algorithm will procedes in a sequential manner, first
+ * yielding the cycle containing the first (in input order) index of the
+ * permutation, then yielding the cycle containing the first (in input order)
+ * index of the permutation that is not in the first cycle, etc. The output is
+ * in the form of an iterator over cycles <code>[a, [b, c, ...]]</code> where
+ * <code>a</code> is the first element of the cycle and the list <code>[b, c,
+ * ...]</code> contains the second, third, etc. elements of the cycle.  The
+ * algorithm uses an helper array to remember which elements have already been
+ * encountered.
+ * @param {Array} sigma The input permutation.
+ * @param {Array} used The helper array.
+ * @returns {Iterator} The cycles <code>[a, [b, c, ...]]</code> for sigma.
+ */
 export function* _cycles ( sigma , used ) {
 
 	for ( const s of sigma ) {

src/_identity.js

@@ -1,11 +1,14 @@
 
+/**
+ * Fills an input array with the identity permutation on input <code>n</code>
+ * elements.
+ *
+ * @param sigma The input array.
+ * @param n The size to use for the permutation.
+ */
 export function _identity ( sigma , n ) {
 
-	for ( let i = 0 ; i < n ; ++i ) {
-
-		sigma[i] = i ;
-
-	}
+	for ( let i = 0 ; i < n ; ++i ) sigma[i] = i ;
 
 }
 

src/_invert.js

@@ -1,11 +1,16 @@
-
+/**
+ * Fills an input array with the inverse <code>rho</code> of the input
+ * permutation <code>sigma</code>, that is, the permutation such that
+ * <code>compose(rho, sigma)</code> returns
+ * <code>identity(sigma.length)</code>.
+ *
+ * @param {Array} sigma 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 ) {
 
-	for ( let i = 0 ; i < n ; ++i ) {
-
-		tau[sigma[i]] = i ;
-
-	}
+	for ( let i = 0 ; i < n ; ++i ) tau[sigma[i]] = i ;
 
 }
 

src/_invertcycles.js

@@ -1,5 +1,11 @@
 import { _transpose } from './_transpose' ;
 
+/**
+ * No idea what this does. Probably inverts the cycles of a given permutation.
+ *
+ * @param {Iterable} cycles The cycles to invert.
+ * @param {Array} tau The given permutation.
+ */
 export function _invertcycles ( cycles , tau ) {
 
 	for ( const [ s , cycle ] of cycles ) {

src/_itranspositions.js

@@ -1,4 +1,11 @@
 
+/**
+ * Really no idead what this does.
+ *
+ * @param {Array} sigma Input permutation.
+ * @param {Array} used Helper array.
+ * @return {Iterator} ?
+ */
 export function* _itranspositions ( sigma , used ) {
 
 	for ( const s of sigma ) {

src/_next.js

@@ -1,6 +1,16 @@
 import { _transpose } from './_transpose' ;
 import { _reverse } from './_reverse' ;
 
+/**
+ * Updates the input permutation to the next one. Returns true unless the input
+ * permutation is the last for its elements. In that case, the input permutation
+ * remains untouched.
+ *
+ * @param {Array} sigma The input permutation.
+ * @param {Number} n The size of the input permutation.
+ * @returns {Boolean} Whether the input permutation is
+ * <underline>NOT</underline> the last for its elements.
+ */
 export function _next ( sigma , n ) {
 
 	let i = n - 1 ;