From d014209a9848706ab70134e66dce93ae67cea64e Mon Sep 17 00:00:00 2001
From: Sergiu Ivanov <sivanov@colimite.fr>
Date: Sun, 29 Nov 2020 21:41:00 +0100
Subject: [PATCH] doc: Add module-level comments for utils.

---
 scribblings/utils.scrbl | 48 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 8 deletions(-)

diff --git a/scribblings/utils.scrbl b/scribblings/utils.scrbl
index 31b5193..60ea56f 100644
--- a/scribblings/utils.scrbl
+++ b/scribblings/utils.scrbl
@@ -1,12 +1,44 @@
 #lang scribble/manual
-@(require (for-label racket graph))
+@(require (for-label racket graph "../utils.rkt"))
 
 @title[#:tag "utils"]{dds/utils: Various Utilities}
 
-@racketblock[
-(define (nobody-understands-me what)
-  (list "When I think of all the"
-        what
-         "I've tried so hard to explain!"))
-(nobody-understands-me "glorble snop")
-]
+@defmodule[dds/utils]
+
+This module defines miscellaneous utilities, supporting the other modules of
+the package: evaluating sexps, manipulating lists,
+@hyperlink["https://orgmode.org/"]{Org-mode} interoperability, etc.
+
+@section{Hashtable injection}
+
+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 hash-ref calls.
+
+@section{Analysis of quoted expressions}
+
+@section{Org-mode interoperability}
+
+Org-mode supports laying out the output of code blocks as tables, which is very
+practical for various variable mappings (e.g., states).  However, when the hash
+table maps variables to lists, Org-mode will create a column per list element,
+which may or may not be the desired effect.  This section defines some
+utilities for nicer interoperation with Org-mode tables.  It also defines some
+shortcuts to reduce the number of words to type when using dds with Org-mode.
+See
+@hyperlink["https://git.marvid.fr/scolobb/dds/src/branch/master/example/example.org"]{example.org}
+for examples of usage.
+
+@section{Additional graph utilities}
+
+@section{Pretty printing}
+
+@section{Additional list and hash map utilities}
+
+@section{Functions and procedures}
+
+@section{Randomness}
+
+@section{Additional stream utilities}
+
+@section{Boolean operations}