From 6cee8a49d97b4af63041c67be4dafcdfe12b2870 Mon Sep 17 00:00:00 2001
From: Sergiu Ivanov <sivanov@colimite.fr>
Date: Fri, 4 Dec 2020 02:25:19 +0100
Subject: [PATCH] utils.scrbl: Add the documentation for types, eval-with, and
 eval1-with.

---
 scribblings/utils.scrbl | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/scribblings/utils.scrbl b/scribblings/utils.scrbl
index b2e412b..84a175d 100644
--- a/scribblings/utils.scrbl
+++ b/scribblings/utils.scrbl
@@ -1,6 +1,8 @@
 #lang scribble/manual
 @(require scribble/example racket/sandbox
-	  (for-label racket graph "../utils.rkt"))
+	  (for-label racket graph "../utils.rkt"
+	  	     (only-in typed/racket/base
+		     	      Any AnyValues)))
 
 @title[#:tag "utils"]{dds/utils: Various Utilities}
 
@@ -15,7 +17,21 @@ the package: evaluating sexps, manipulating lists,
   (parameterize ([sandbox-output 'string]
   		 [sandbox-error-output 'string]
 		 [sandbox-memory-limit 50])
-   (make-evaluator 'racket/base #:requires '("utils.rkt"))))
+   (make-evaluator 'typed/racket/base #:requires '("utils.rkt"))))
+
+@section{Base Types}
+@defidform[Variable]{
+
+Any Racket symbol.  Designates a variable in a discrete dynamical network.
+
+}
+
+@defform[(VariableMapping A)]{
+
+An immutable mapping (a hash table) assigning elements of type @racket[A] to
+the variables.
+
+}
 
 @section{Hashtable injection}
 
@@ -23,7 +39,7 @@ This section defines some utilities to streamline the usage of hash tables
 mapping symbols to values.  The goal is essentially to avoid having to write
 explicit @racket[hash-ref] calls.
 
-@defproc[(eval-with [ht variable-mapping?] [expr any/c]) any]{
+@defproc[(eval-with [ht (VariableMapping Any)] [expr Any]) AnyValues]{
 
 Temporarily injects the mappings from the given hash table as bindings in
 a namespace including @racket[racket/base] and then evaluates the expression.
@@ -44,6 +60,15 @@ missing identifier:
   (eval-with ht '(+ b z a 1)))
 )]}
 
+@defproc[(eval1-with [ht (VariableMapping Any)] [expr Any]) Any]{
+
+Like @racket[eval-with], but returns only the first value computed by
+@racket[expr].
+
+@examples[#:eval utils-evaluator
+(let ([ht (hash 'a 1 'b 1)])
+  (eval1-with ht '(+ b a 1)))
+]}
 @section{Analysis of quoted expressions}
 
 @section{Org-mode interoperability}