more documentation

Author: make-github-pseudonymous-again

src/base/_count.js

@@ -1,3 +1,19 @@
+/**
+ * Yields increasing or decreasing sequences of numbers. The starting value
+ * and the step between separating output values can be chosen.
+ *
+ * @example
+ * // equivalent to list( range( 7 ) )
+ * list( head( _count( 0 , 1 ) , 7 ) ) ;
+ *
+ * @example
+ * // returns [0,-1,-2,-3,-4]
+ * list( head( _count( 0 , -1 ) , 5 ) ) ;
+ *
+ * @param {Number} start - The starting value.
+ * @param {Number} step - The step between the values.
+ * @returns {Iterator}
+ */
 export function* _count ( start , step ) {
 
 	while ( true ) {

src/base/_next.js

@@ -1,3 +1,9 @@
+/**
+ * Returns the next event of the input iterator.
+ *
+ * @param {Iterator} iterator - The input iterator.
+ * @returns {{done: Boolean, value: Object}}
+ */
 export function _next ( iterator ) {
 
 	return iterator.next( ) ;

src/base/_range.js

@@ -1,3 +1,13 @@
+/**
+ * Yields values in a range, separated by a fixed constant called step. If
+ * this step is negative, the range has to be given in reverse order, that is,
+ * largest value first, smallest value second.
+ *
+ * @param {Number} start - The starting value.
+ * @param {Number} stop - The stopping value.
+ * @param {Number} step - The step value.
+ * @returns {Iterator}
+ */
 export function* _range ( start , stop , step ) {
 
 	if ( step < 0 ) {

src/base/by.js

@@ -1,6 +1,14 @@
 import { iter } from './iter' ;
 import { range } from './range' ;
 
+/**
+ * Yields elements of the input iterable by grouping them into tuples of a
+ * given size.
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The size of the yielded tuples.
+ * @returns {Iterator}
+ */
 export function* by ( iterable , n ) {
 
 	const iterator = iter( iterable ) ;

src/base/consume.js

@@ -1,3 +1,10 @@
+/**
+ * Consumes a given number of iterations of the input iterator.
+ *
+ * @param {Iterator} iterator - The input iterator.
+ * @param {Number} n - The number of iterations to consume.
+ *
+ */
 export function consume ( iterator , n ) {
 
 	while ( n --> 0 && !iterator.next().done ) ;

src/base/count.js

@@ -1,5 +1,23 @@
 import { _count } from './_count' ;
 
+/**
+ * Yields increasing or decreasing sequences of numbers. The starting value
+ * and the step between separating output values can be chosen. Both parameters are
+ * optional. The default for the starting value is <code>0</code>. The default
+ * for the step between separating output values is <code>1</code>.
+ *
+ * @example
+ * // equivalent to list( range( 7 ) )
+ * list( head( count( ) , 7 ) ) ;
+ *
+ * @example
+ * // returns [0,-1,-2,-3,-4]
+ * list( head( count( 0 , -1 ) , 5 ) ) ;
+ *
+ * @param {Number} [start=0] - The starting value.
+ * @param {Number} [step=1] - The step between the values.
+ * @returns {Iterator}
+ */
 export function count ( start = 0 , step = 1 ) {
 
 	return _count( start , step ) ;

src/base/cycle.js

@@ -1,3 +1,14 @@
+/**
+ * Cycles through the input iterable.
+ *
+ * @example
+ * // returns [0,1,0,1,0,1,0]
+ * list(head(cycle(range(2)),7)) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ *
+ */
 export function* cycle ( iterable ) {
 
 	let buffer = [ ] ;

src/base/drop.js

@@ -2,6 +2,13 @@ import { iter } from './iter' ;
 import { consume } from './consume' ;
 import { tail } from './tail' ;
 
+/**
+ * Drops the first <code>n</code> elements of the input iterable.
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The number of elements to drop.
+ * @returns {Iterator}
+ */
 export function drop ( iterable , n ) {
 
 	if ( n < 0 ) return tail( iterable , -n ) ;

src/base/next.js

@@ -1,5 +1,12 @@
 import { StopIteration } from './StopIteration' ;
 
+/**
+ * Returns the next value of the input iterator. If there the iterator is
+ * exhausted, throws a {@link StopIteration}.
+ *
+ * @param {Iterator} iterator - The input iterator.
+ * @returns {Object}
+ */
 export function next ( iterator ) {
 
 	const x = iterator.next( ) ;

src/base/range.js

@@ -1,5 +1,17 @@
 import { _range } from './_range' ;
 
+/**
+ * Yields values in a range, separated by a fixed constant called step. If this
+ * step is negative, the range has to be given in reverse order, that is,
+ * largest value first, smallest value second. Both the starting value and the
+ * step value are optional. By default the starting value is <code>0</code>.
+ * The default for the step value is <code>1</code>.
+ *
+ * @param {Number} [start=0] - The starting value.
+ * @param {Number} stop - The stopping value.
+ * @param {Number} [step=1] - The step value.
+ * @returns {Iterator}
+ */
 export function range ( start , stop , step ) {
 
 	if ( stop === undefined ) return _range( 0 , start , 1 ) ;