From 582244bd6a71a645cc772362dc75aa3a3e948c9a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 3 Oct 2023 14:15:16 +0200
Subject: Improve lens documentation.

---
 doc/ref/general/lens.texi | 53 +++++++++++++++++++++++++++++++++--------------
 1 file changed, 38 insertions(+), 15 deletions(-)

diff --git a/doc/ref/general/lens.texi b/doc/ref/general/lens.texi
index a07dd7c9..144478c3 100644
--- a/doc/ref/general/lens.texi
+++ b/doc/ref/general/lens.texi
@@ -3,38 +3,61 @@
 
 Provided by the module @code{(hnh util lens)}
 
-@c TODO write an actuall introduction here
+A lens system for Scheme. All these procedures are pure. In general,
+procedures fetching values from objects return that value, while
+procedures ``setting'' or ``mutating'' objects returns a new instance
+of the object, with the field in question replaced.
 
-@defun modify object lens f args ...
-@end defun
+Lenses aren't a special type, but rather procedures which return a
+value when called with one argument, and produce a new container with
+an updated value when called with two arguments.
 
-@defmac modify* object lens
-@defmacx modify* object lens rest ...
-@end defmac
+For example, the lens to focus the first element of a pair is
+implemented as:
 
-@defmac set object lenses ... value
-@end defmac
+@lisp
+(define car*
+  (case-lambda ((pair) (car pair))
+               ((pair value) (cons value (cdr pair)))))
+@end lisp
+
+@defun compose-lenses lenses ...
+@defunx lens-compose lenses ...
+Creates a new lens, which is the compound from all the given lenses.
+
+Lenses composes left to right, so earlier lenses in @var{lenses} are
+applied earlier.
+@end defun
 
 @defmac get object lenses ...
+Do a deep lookup. Lenses are composed as per @code{compose-lenses}.
 @end defmac
 
+@defmac set object lenses ... value
+Do a deep update of a field, and return a new object with the focused
+element replaced. Lenses are composed as per @code{compose-lenses}.
+@end defmac
 
-@defun make-lens getter setter
+@defun modify object lens f args ...
+Returns a new object, with the value focused by @var{lens} replaced by
+the result of calling @var{f}, with the old value, and the extra
+arguments given.
 @end defun
 
+@defmac modify* object lens ... f
+Like @code{modify}, but auto compose lenses, and don't allow extra
+arguments to @var{f}.
+@end defmac
+
 @defmac build-lens getter setter
 Where any of getter or setter can either be a single symbol, or a list.
 @end defmac
 
 @deftp {Scheme Lens} identity-lens
+A lens focusing the given object. Showing the value returns the root
+value, and setting the value just returns the new value.
 @end deftp
 
-@defun compose-lenses lenses ...
-@defunx lens-compose lenses ...
-Lenses composes left to right, so earlier lenses in @var{lenses} are
-applied earlier.
-@end defun
-
 @deftp {Scheme Lens} ref idx
 Focuses the element at index @var{idx} in a list.
 @end deftp
-- 
cgit v1.2.3