📚 docs: Improve signatures and assertions.

Author: make-github-pseudonymous-again

src/Node.js

@@ -1,10 +1,14 @@
 /**
  * Base node class.
  *
- * @param {Object} value - The value to hold.
+ * @class
+ * @param {any} value The value to hold.
  */
 export default function Node(value) {
-	this.value = value; // Key
-	this.prev = this; // Pointer to previous (left) sibling
-	this.next = this; // Pointer to next (right) sibling
+	/** @member {any} The value/key held by this node. */
+	this.value = value;
+	/** @member {Node} Pointer to previous (left) sibling */
+	this.prev = this;
+	/** @member {Node} Pointer to next (right) sibling */
+	this.next = this;
 }

src/_append.js

@@ -1,15 +1,18 @@
 import assert from 'assert';
+import Node from './Node.js';
 
 /**
  * Optimization of {@link _concat} when <code>x</code> contains a single element.
  * Works even if <code>x</code> has dangling pointers <code>x.next</code> and <code>x.prev</code>.
  *
- * @param {Node} a - First node of list.
- * @param {Node} x - Node to be inserted at the end of list.
+ * @param {Node} a First node of list.
+ * @param {Node} x Node to be inserted at the end of list.
  */
 export default function _append(a, x) {
-	assert(a !== null && x !== null);
-	assert(x.next === x && x.prev === x);
+	assert(a instanceof Node);
+	assert(x instanceof Node);
+	assert(x.next === x);
+	assert(x.prev === x);
 	// FROM a - b - c - d - a        x
 	//   TO a - b - c - d - x - a
 	const d = a.prev;

src/_concat.js

@@ -1,13 +1,15 @@
 import assert from 'assert';
+import Node from './Node.js';
 
 /**
  * Concatenate two input lists.
  *
- * @param {Node} x - First node of first input list.
- * @param {Node} y - First node of second input list.
+ * @param {Node} x First node of first input list.
+ * @param {Node} y First node of second input list.
  */
 export default function _concat(x, y) {
-	assert(x !== null && y !== null);
+	assert(x instanceof Node);
+	assert(y instanceof Node);
 	// FROM x - b - c - d - x        y - f - g - h - y
 	//   TO x - b - c - d - y - f - g - h - x
 	const d = x.prev;

src/_iter.js

@@ -1,13 +1,16 @@
 import assert from 'assert';
+import Node from './Node.js';
 
 /**
  * Generator of nodes in list in order.
  *
- * @param {Node} first - First node of the list.
- * @return {Iterable}
+ * TODO yield values/keys instead?
+ *
+ * @param {Node} first First node of the list.
+ * @return {IterableIterator} Yields nodes of a list in order.
  */
 export default function* _iter(first) {
-	assert(first !== null);
+	assert(first instanceof Node);
 	let next = first;
 
 	do {

src/_remove.js

@@ -1,15 +1,16 @@
 import assert from 'assert';
+import Node from './Node.js';
 
 /**
  * Removes input {@link Node} from its list.
  *
  * /!\ Pointers in the extracted node are left unchanged.
  * /!\ <code>x</code> will have dangling pointers after removal if not single element.
  *
- * @param {Node} x - Node to remove.
+ * @param {Node} x Node to remove.
  */
 export default function _remove(x) {
-	assert(x !== null);
+	assert(x instanceof Node);
 	x.prev.next = x.next;
 	x.next.prev = x.prev;
 }

src/concat.js

@@ -5,8 +5,9 @@ import _concat from './_concat.js';
 /**
  * Concatenate two input lists.
  *
- * @param {Node} x - First node of first input list (can be null).
- * @param {Node} y - First node of second input list (can be null).
+ * @param {Node} x First node of first input list (can be null).
+ * @param {Node} y First node of second input list (can be null).
+ * @return {Node} First node of the output list (or null if empty).
  */
 export default function concat(x, y) {
 	if (x === null) return y;

src/from.js

@@ -4,7 +4,8 @@ import _append from './_append.js';
 /**
  * Creates a list from an input iterable.
  *
- * @param {Iterable} iterable - The input iterable.
+ * @param {Iterable} iterable The input iterable.
+ * @return {Node} First node of the newly created list (or null if empty list).
  */
 export default function from(iterable) {
 	const it = iterable[Symbol.iterator]();

src/iter.js

@@ -1,10 +1,14 @@
+import assert from 'assert';
 import _iter from './_iter.js';
+import Node from './Node.js';
+
 /**
  * Generator of nodes in list in order.
  *
- * @param {Node} first - First node of the list (can be null).
- * @return {Iterable}
+ * @param {Node} first First node of the list (can be null).
+ * @return {IterableIterator}
  */
 export default function* iter(first) {
+	assert(first === null || first instanceof Node);
 	if (first !== null) yield* _iter(first);
 }

src/pop.js

@@ -3,9 +3,9 @@ import Node from './Node.js';
 import _remove from './_remove.js';
 
 /**
- * Removes last {@link Node} from a list.
+ * Removes last {@link Node} from a list. Throws if input list is empty.
  *
- * @param {Node} x - First node .
+ * @param {Node} x First node.
  * @return {[Node, Node]} New list (possibly null) and popped node.
  */
 export default function pop(x) {

src/push.js

@@ -5,8 +5,10 @@ import _append from './_append.js';
 /**
  * Push value to list.
  *
- * @param {Node} x - First node of first input list (can be null).
- * @param {Object} value - Value to push.
+ * @param {Node} x First node of first input list (can be null).
+ * @param {any} value Value to push.
+ * @return {Node} The node at the front of the list (new node if empty, input
+ * node otherwise).
  */
 export default function push(x, value) {
 	if (x === null) return new Node(value);