finish base documentation

Author: make-github-pseudonymous-again

src/base/StopIteration.js

@@ -1 +1,5 @@
+/**
+ * Error thrown by {@link next} when the input iterator is exhausted.
+ * @class
+ */
 export function StopIteration ( ) { }

src/base/drop.js

@@ -4,6 +4,12 @@ import { tail } from './tail' ;
 
 /**
  * Drops the first <code>n</code> elements of the input iterable.
+ * If <code>n</code> is negative, behaves like <code>{@link tail}( iterable,
+ * -n)</code>.
+ *
+ * @example
+ * // returns [ 3 , 4 ]
+ * list( drop( range( 5 ) , 3 ) ) ;
  *
  * @param {Iterable} iterable - The input iterable.
  * @param {Number} n - The number of elements to drop.

src/base/exhaust.js

@@ -1,3 +1,14 @@
+/**
+ * Exhausts the input iterator.
+ *
+ * @example
+ * let it = range( 1000 ) ;
+ * exhaust( it ) ;
+ * list( it ) ; // returns []
+ *
+ * @param {Iterator} iterator - The input iterator.
+ *
+ */
 export function exhaust ( iterator ) {
 
 	for ( let item of iterator ) ;

src/base/frame.js

@@ -1,6 +1,20 @@
 import { iter } from './iter' ;
 import { range } from './range' ;
 
+/**
+ * Yields tuples that contain the current element of the input iterable and the
+ * next <code>n-1</code> elements of the input iterable.
+ *
+ * @example
+ * frame( range( 100 ) , 2 ) ;
+ * // is equivalent to
+ * zip( range( 100 ) , range( 1 , 100 ) ) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The frame size.
+ * @returns {Iterator}
+ *
+ */
 export function* frame ( iterable , n ) {
 
 	// Could have an implementation using a deque

src/base/head.js

@@ -1,3 +1,7 @@
 import { take } from './take' ;
 
+/**
+ * @function head
+ * Same as {@link take}.
+ */
 export const head = take ;

src/base/iter.js

@@ -1,3 +1,10 @@
+/**
+ * Returns the iterator for the input iterable.
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ *
+ */
 export function iter ( iterable ) {
 
 	return iterable[Symbol.iterator]( ) ;

src/base/len.js

@@ -1,5 +1,16 @@
-export function len ( list ) {
+/**
+ * Returns the length of the input array.
+ *
+ * @example
+ * // returns 7
+ * len( list( range( 7 ) ) ) ;
+ *
+ * @param {Array} array - The input array.
+ * @returns {Number}
+ *
+ */
+export function len ( array ) {
 
-	return list.length ;
+	return array.length ;
 
 }

src/base/list.js

@@ -1,3 +1,14 @@
+/**
+ * Returns an array containing all elements of the input iterable.
+ *
+ * @example
+ * // return [0,1,2]
+ * list( range( 3 ) ) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Array}
+ *
+ */
 export function list ( iterable ) {
 
 	return Array.from( iterable ) ;

src/base/ncycle.js

@@ -1,3 +1,15 @@
+/**
+ * Same as {@link cycle} but only cycles a limited number of times.
+ *
+ * @example
+ * // returns [0,1,0,1,0,1,0,1]
+ * list(ncycle(range(2),4)) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The number of times to cycle through the input iterable.
+ * @returns {Iterator}
+ *
+ */
 export function* ncycle ( iterable , n ) {
 
 	let buffer = [ ] ;

src/base/pick.js

@@ -1,3 +1,15 @@
+/**
+ * Yields some of the properties of the input object. The properties to yield
+ * are designated by the input iterable.
+ *
+ * @example
+ * // returns [ 'a' , 'e' , 'c' ]
+ * list( pick( 'abcde' , [ 0 , 4 , 2 ] ) ) ;
+ *
+ * @param {Object} object - The input object.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ */
 export function* pick ( object , iterable ) {
 
 	for ( let key of iterable ) yield object[key] ;

src/base/tail.js

@@ -1,6 +1,19 @@
 import { iter } from './iter' ;
 import { drop } from './drop' ;
 
+/**
+ * Returns the last <code>n</code> elements of the input iterable in an array.
+ * If <code>n</code> is negative, behaves like <code>{@link drop}( iterable,
+ * -n)</code>.
+ *
+ * @example
+ * // returns [ 3 , 4 ]
+ * list( tail( range( 5 ) , 2 ) ) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The number of elements to include in the output.
+ * @returns {Array} - The last <code>n</code> elements of the input iterable.
+ */
 export function tail ( iterable , n ) {
 
 	if ( n < 0 ) return drop( iterable , -n ) ;

src/base/take.js

@@ -1,6 +1,19 @@
 import { iter } from './iter' ;
 import { trunc } from './trunc' ;
 
+/**
+ * Yields the first <code>n</code> elements of the input iterable. If
+ * <code>n</code> is negative, behaves like <code>{@link trunc}( iterable,
+ * -n)</code>.
+ *
+ * @example
+ * // returns [ 0 , 1 , 2 ]
+ * list( take( range( 5 ) , 3 ) ) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The number of elements to include in the output.
+ * @returns {Iterator} - The first <code>n</code> elements of the input iterable.
+ */
 export function* take ( iterable , n ) {
 
 	if ( n < 0 ) {

src/base/tee.js

@@ -2,6 +2,13 @@ import { iter } from './iter' ;
 import { list } from './list' ;
 import { map } from '../map/map' ;
 
+/**
+ * Returns <code>n</code> copies of the input iterable.
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The number of copies to make.
+ * @returns {Iterator[]}
+ */
 export function tee ( iterable , n ) {
 
 	let iterator = iter( iterable ) ;

src/base/trunc.js

@@ -1,6 +1,19 @@
 import { iter } from './iter' ;
 import { take } from './take' ;
 
+/**
+ * Yields all elements of the iterable except the last <code>n</code> ones. If
+ * <code>n</code> is negative, behaves like <code>{@link take}( iterable, -n
+ * )</code>.
+ *
+ * @example
+ * // returns [ 0 , 1 , 2 ]
+ * list( trunc( range( 5 ) , 2 ) ) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The number of elements to exclude from the output.
+ * @returns {Iterator}
+ */
 export function* trunc ( iterable , n ) {
 
 	if ( n < 0 ) {

src/map/filter.js

@@ -23,9 +23,7 @@ export function* filter ( predicate , iterable ) {
 }
 
 /**
+ * @function filtertrue
  * Same as {@link filter}.
- *
- * @function
- *
  */
 export const filtertrue = filter ;