From 15b8169ce4bbba4d036544ed15fffb7188dea6db Mon Sep 17 00:00:00 2001
From: crc <>
Date: Mon, 23 Jan 2023 15:44:42 +0000
Subject: [PATCH] fll: more commentary

FossilOrigin-Name: 700ca74a200346f7542002663d11261aa4889be1778b4c2ea1f398b18d4e6bc1
---
 interface/ll.retro | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/interface/ll.retro b/interface/ll.retro
index 326a618..fa14b7c 100644
--- a/interface/ll.retro
+++ b/interface/ll.retro
@@ -79,19 +79,32 @@ a pointer to the final cons cell.
 }}
 ~~~
 
+Appening a value is simple. Create a new cons with the value in
+the car and a pointer to END in the cdr. Find the end of the
+list, and update the cdr to point to the new cons.
+
 ~~~
 :fll:append/value (pv-) &END cons swap fll:to-end cdr! ;
 ~~~
 
+Given a specific node in the list, follow the cdr chain until
+the node number is reached. Starts at zero.
+
+An issue with this: it does not currently check the length to
+make sure that the index is valid.
+
 ~~~
 :fll:to-index (pn-p) [ cdr@ ] times ;
 ~~~
 
+
 ~~~
 :fll:del
   dup-pair n:dec fll:to-index [ n:inc fll:to-index ] dip cdr! ;
 ~~~
 
+The `fll:for-each` runs a quote once for each value in a list.
+
 ~~~
 {{
   'Action var
@@ -102,14 +115,22 @@ a pointer to the final cons cell.
 }}
 ~~~
 
+To obtain the length of a list (in number of cons) use
+`fll:length`.
+
 ~~~
 :fll:length (p-n) #0 swap [ drop n:inc ] fll:for-each n:dec ;
 ~~~
 
+`fll:drop` removes the a specified cons from a list.
+
 ~~~
 :fll:drop dup fll:length n:dec fll:to-index &END swap cdr! ;
 ~~~
 
+`fll:inject` adds a new cons to a list, inserting at a specified
+point.
+
 ~~~
 {{
   'i var