finish documentation of src/map

Author: make-github-pseudonymous-again

src/map/_zip.js

@@ -1,4 +1,3 @@
-
 import { list , map , iter , _next } from '..' ;
 
 /**

src/map/_zip2.js

@@ -1,4 +1,3 @@
-
 import { iter } from '..' ;
 
 /**

src/map/combinations.js

@@ -1,10 +1,21 @@
 import { list , range , pick } from '..' ;
 
 /**
- * @example combinations('ABCD', 2) // AB AC AD BC BD CD
- * @example combinations(range(4), 3) // 012 013 023 123
+ * Yields all combinations of each possible choice of <code>r</code> elements
+ * of the input iterable.
+ *
+ * @example
+ * // AB AC AD BC BD CD
+ * combinations('ABCD', 2)
+ *
+ * @example
+ * // 012 013 023 123
+ * combinations(range(4), 3)
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} r - The size of the combinations to generate.
+ * @returns {Iterator}
  */
-
 export function* combinations ( iterable , r ) {
 
 	let pool = list( iterable ) ;

src/map/combinationswithrepetition.js

@@ -1,8 +1,20 @@
 import { list , nrepeat , pick } from '..' ;
 
 /**
- * @example combinationswithrepetition('ABC', 1) // A B C
- * @example combinationswithrepetition(range(3), 2) // 00 01 02 11 12 22
+ * Yields all combinations, with repetitions, of each possible choice of
+ * <code>r</code> elements of the input iterable.
+ *
+ * @example
+ * // A B C
+ * combinationswithrepetition('ABC', 1)
+ *
+ * @example
+ * // 00 01 02 11 12 22
+ * combinationswithrepetition(range(3), 2)
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} r - The size of the combinations to generate.
+ * @returns {Iterator}
  */
 
 export function* combinationswithrepetition ( iterable , r ) {

src/map/compress.js

@@ -1,6 +1,15 @@
-
 import { _zip2 } from '..' ;
 
+/**
+ * Filters the first input iterable according to truthy and flasy values from a
+ * second input iterable. The ith element of the first input iterable is output
+ * if and only if the ith element of the second input iterable is truthy.
+ *
+ * @param {Iterable} iterable - The first input iterable to filter.
+ * @param {Iterable} selector - The second input iterable containing the truthy and falsy
+ * values.
+ * @returns {Iterator}
+ */
 export function* compress ( iterable , selector ) {
 
 	for ( let [ take , item ] of _zip2( selector , iterable ) ) {

src/map/dropwhile.js

@@ -1,6 +1,13 @@
-
 import { iter } from '..' ;
 
+/**
+ * Drop elements of the input iterable while the current element satisfies the
+ * input predicate.
+ *
+ * @param {Function} predicate - The input predicate.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ */
 export function* dropwhile ( predicate , iterable ) {
 
 	let iterator = iter( iterable ) ;

src/map/filter.js

@@ -1,4 +1,3 @@
-
 /**
  * Yields all elements from input iterable that verify a given predicate.
  *

src/map/group.js

@@ -1,6 +1,14 @@
-
 import { iter } from '..' ;
 
+/**
+ * Yields elements of the input iterable by grouping them into tuples
+ * consecutive elements from the same equivalence class.
+ *
+ * @param {Function} key - The function used to determine the equivalence class
+ * of an element.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ */
 export function* group ( key , iterable ) {
 
 	let iterator = iter( iterable ) ;
@@ -48,4 +56,8 @@ export function* group ( key , iterable ) {
 
 }
 
+/**
+ * Same as {@link group}.
+ * @function groupby
+ */
 export const groupby = group ;

src/map/map.js

@@ -1,4 +1,14 @@
-
+/**
+ * Applies a given callable to each of the elements of the input iterable.
+ *
+ * @example
+ * // return [ 0 , 1 , 4 , 9 ]
+ * list( map( x => x**2 , range( 4 ) ) ) ;
+ *
+ * @param {Function} callable - The callable to use.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ */
 export function* map ( callable , iterable ) {
 
 	for ( let item of iterable ) yield callable( item ) ;

src/map/nrepeat.js

@@ -1,4 +1,3 @@
-
 /**
  * Repeats the input item a few times. Returns an iterator that yields the input
  * item a fixed number of times.

src/map/product.js

@@ -1,4 +1,3 @@
-
 import { list , map , _product , ncycle , reversed } from '..' ;
 
 /**

src/map/repeat.js

@@ -1,4 +1,3 @@
-
 /**
  * Repeats the input item endlessly. Returns an iterator that yields the input
  * item over and over again.

src/map/reversed.js

@@ -1,4 +1,9 @@
-
+/**
+ * Yields elements of the input iterable in reverse order.
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator} - The input iterable, reversed.
+ */
 export function* reversed ( iterable ) {
 
 	let buffer = [ ] ;

src/map/slice.js

@@ -1,6 +1,16 @@
-
 import { iter } from '..' ;
 
+/**
+ * Same as
+ * <code>map( [ i , x ] => x , filter( [ i , x ] => (new Set( range( start ,
+ * stop , step ) ) ).has( i ) , enumerate( iterable ) ) );</code>.
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} start - Where to start the slice.
+ * @param {Number} stop - Where to stop the slice.
+ * @param {Number} step - The step of the slice.
+ * @returns {Iterator}
+ */
 export function* slice ( iterable , start , stop , step ) {
 
 	let iterator = iter( iterable ) ;

src/map/sorted.js

@@ -1,6 +1,16 @@
-
 import { list } from '../base/list' ;
 
+/**
+ * Outputs an array containing the elements of the input iterable sorted
+ * according to a given comparison function.
+ *
+ * @param {Function} compare - The comparison function to use. This function
+ * must be 2-ary. It must return -1, 0, or 1 depending whether the first
+ * parameter is, respectively, less than, equal to, or greater than the second
+ * parameter.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Array} - The input iterable, sorted.
+ */
 export function sorted ( compare , iterable ) {
 
 	return list( iterable ).sort( compare ) ;

src/map/starmap.js

@@ -1,7 +1,17 @@
-
+/**
+ * Same as {@link map} but allows multiple arguments callable functions.
+ *
+ * @example
+ * // return [ 0 , 1 , 4 , 9 ]
+ * list( starmap( ( x , y ) => x*y , zip( range( 4 ) , range( 4 ) ) ) ;
+ *
+ * @param {Function} callable - The callable to use.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ */
 export function* starmap ( callable , iterable ) {
 
-	for ( let item of iterable ) yield callable.apply( null , item ) ;
-	//for ( let args of iterable ) yield callable( ...args ) ;
+	for ( let args of iterable ) yield callable.apply( null , args ) ;
+	//for ( let args of iterable ) yield callable( ... ) ;
 
 }

src/map/takewhile.js

@@ -1,4 +1,11 @@
-
+/**
+ * Output elements of the input iterable while the current element satisfies the
+ * input predicate.
+ *
+ * @param {Function} predicate - The input predicate.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ */
 export function* takewhile ( predicate , iterable ) {
 
 	for ( let item of iterable ) {

src/map/zip.js

@@ -1,4 +1,3 @@
-
 import { _zip } from './_zip' ;
 
 /**

src/map/ziplongest.js

@@ -1,4 +1,3 @@
-
 import { _ziplongest } from './_ziplongest' ;
 
 /**