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 ;

src/_permutations.js

@@ -1,5 +1,14 @@
 import { _next } from './_next' ;
 
+/**
+ * Yields all permutations starting from a given one and ending at the last
+ * 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
+ * and the last permutation on its elements.
+ */
 export function* _permutations ( sigma , n ) {
 
 	do { yield sigma ; } while ( _next( sigma , n ) ) ;

src/_reverse.js

@@ -1,5 +1,13 @@
 import { _transpose } from './_transpose' ;
 
+/**
+ * Reverses input permutation in place from input index <code>i</code>
+ * (include) to input index <code>j</code> (excluded).
+ *
+ * @param {Array} sigma The input permutation to reverse.
+ * @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

@@ -1,4 +1,12 @@
 
+/**
+ * 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 {Array} sigma The input permutation.
+ */
 export function _transpose ( a , b , sigma ) {
 
 	const tmp = sigma[a] ;

src/_transposition.js

@@ -1,4 +1,13 @@
 
+/**
+ * Helper method for {@link transposition}.
+ * 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 {Array} sigma Input permutation.
+ */
 export function _transposition ( a , b , sigma ) {
 
 	sigma[a] = b ;

src/_transpositions.js

@@ -1,3 +1,11 @@
+/**
+ * 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
+ * defined by the input cycles.
+ */
 export function* _transpositions ( cycles ) {
 
 	for ( const [ s , cycle ] of cycles ) {
@@ -7,4 +15,3 @@ export function* _transpositions ( cycles ) {
 	}
 
 }
-

src/_used.js

@@ -1,4 +1,14 @@
 
+/**
+ * For a given size <code>n</code>, fills an input array with
+ * <code>false</code>. Starting at index <code>0</code>, ending at index
+ * <code>n-1</code>. This array is used as a helper in other function. For
+ * example, for computing the cycle decomposition of an input permutation (see
+ * {@link _cycles}, {@link cycles}).
+ *
+ * @param n The given size.
+ * @param array The input array.
+ */
 export function _used ( n , array ) {
 
 	for ( let i = 0 ; i < n ; ++i ) array[i] = false ;

src/apply.js

@@ -1,6 +1,15 @@
 import { identity } from './identity' ;
 import { _apply } from './_apply' ;
 
+/**
+ * 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 n The size of the identity permutation to apply the transpositions
+ * to.
+ * @param transpositions The given transpositions to apply.
+ * @returns {Array} The resulting permutation.
+ */
 export function apply ( n , transpositions ) {
 
 	const rho = identity( n ) ;

src/bitreversal.js

@@ -1,6 +1,15 @@
 import { permutation } from './permutation' ;
 import { _bitreversal } from './_bitreversal' ;
 
+/**
+ * Returns a newly allocated array containing the bitreversal permutation for
+ * 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
+ * <code>2</code>.
+ * @returns {Array} The bitreversal permutation of size <code>n</code>.
+ */
 export function bitreversal ( n ) {
 
 	const sigma = permutation( n ) ;

src/compose.js

@@ -1,8 +1,18 @@
 import { permutation } from './permutation' ;
 import { _compose } from './_compose' ;
 
+/**
+ * Compose two input permutations. The resulting permutation is output as an
+ * array of indices.
+ *
+ * @param {Array} sigma The first input permutation.
+ * @param {Array} tau The second input permutation.
+ * @returns {Array} The resulting permutation as an array.
+ */
 export function compose ( sigma , tau ) {
 
+	// TODO replace with Array.from( _compose...
+
 	const rho = permutation( sigma.length ) ;
 
 	let i = 0 ;

src/copy.js

@@ -1,6 +1,12 @@
 import { permutation } from './permutation' ;
 import { _copy } from './_copy' ;
 
+/**
+ * Make a copy of the input permutation.
+ *
+ * @param {Array} sigma The input permutation.
+ * @returns {Array} The copy.
+ */
 export function copy ( sigma ) {
 
 	const rho = permutation( sigma.length ) ;

src/cycles.js

@@ -1,6 +1,14 @@
 import { _cycles } from './_cycles' ;
 import { used } from './used' ;
 
+
+/**
+ * Computes the cycle decomposition of the input permutation.
+ * See {@link _cycles} for implementation.
+ *
+ * @param {Array} sigma The input permutation.
+ * @returns {Iterator} The cycles <code>[a, [b, c, ...]]</code> for sigma.
+ */
 export function* cycles ( sigma ) {
 
 	yield* _cycles( sigma , used( sigma.length ) ) ;

src/identity.js

@@ -1,6 +1,12 @@
 import { permutation } from './permutation' ;
 import { _identity } from './_identity' ;
 
+/**
+ * Returns the identity permutation of a given size.
+ *
+ * @param {Number} n The size of the permutation to return.
+ * @returns {Array} The identity permutation on <code>n</code> elements.
+ */
 export function identity ( n ) {
 
 	const rho = permutation( n ) ;

src/invert.js

@@ -1,6 +1,14 @@
 import { permutation } from './permutation' ;
 import { _invert } from './_invert' ;
 
+/**
+ * Computes 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.
+ * @returns {Array} The inverse of the input permutation.
+ */
 export function invert ( sigma ) {
 
 	const rho = permutation( sigma.length ) ;

src/itranspositions.js

@@ -1,6 +1,12 @@
 import { _itranspositions } from './_itranspositions' ;
 import { used } from './used' ;
 
+/**
+ * Really no idead what this does, see also {@link _itranspositions}.
+ *
+ * @param {Array} sigma Input permutation.
+ * @return {Iterator} ?
+ */
 export function* itranspositions ( sigma ) {
 
 	yield* _itranspositions( sigma , used( sigma.length ) ) ;

src/next.js

@@ -2,6 +2,14 @@ import { copy } from './copy' ;
 import { _next } from './_next' ;
 import { reverse } from './reverse' ;
 
+/**
+ * Computes the permutation that follows the input permutation. If the input
+ * permutation is the last for its elements, return the first for its elements.
+ * The input permutation is not altered.
+ *
+ * @param {Array} sigma The input permutation.
+ * @returns {Array} The next permutation.
+ */
 export function next ( sigma ) {
 
 	const rho = copy( sigma ) ;