📚 docs: Improve docstrings.

Author: make-github-pseudonymous-again

src/_iter.js

@@ -2,12 +2,14 @@ import assert from 'assert';
 import Node from './Node.js';
 
 /**
- * Generator of nodes in list in order.
+ * Generator of nodes in list in order. You are allowed to edit the current
+ * node.
  *
- * TODO yield values/keys instead?
+ * /!\ Modifying the next pointer of the current node will NOT change which
+ * node comes next in the iteration.
  *
  * @param {Node} first First node of the list.
- * @return {IterableIterator} Yields nodes of a list in order.
+ * @return {IterableIterator<Node>} Yields nodes of a list in order.
  */
 export default function* _iter(first) {
 	assert(first instanceof Node);

src/iter.js

@@ -6,7 +6,7 @@ import Node from './Node.js';
  * Generator of nodes in list in order.
  *
  * @param {Node} first First node of the list (can be null).
- * @return {IterableIterator}
+ * @return {IterableIterator<Node>}
  */
 export default function* iter(first) {
 	assert(first === null || first instanceof Node);

src/pop.js

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

src/shift.js

@@ -5,11 +5,8 @@ import _remove from './_remove.js';
 /**
  * Removes first {@link Node} from a list. Throws if input list is empty.
  *
- * TODO I do not think we need to return the popped node since it is x.
- *      Currently this is kept so to have the same signature as {@link pop}.
- *
  * @param {Node} x First node .
- * @return {[Node, Node]} New list (possibly null) and popped node.
+ * @return {[Node, Node]} New list (possibly null) and removed node.
  */
 export default function shift(x) {
 	if (x === null) throw new Error('input list is empty');