From 0387cbc7eb50336fa8272bee959f05c8d5aab2b7 Mon Sep 17 00:00:00 2001
From: Emery Hemingway <ehmry@posteo.net>
Date: Mon, 25 Oct 2021 19:07:16 +0200
Subject: [PATCH] Update documentation

---
 README.md         | 17 ++++++++++++++++-
 src/preserves.nim | 16 +++++++++++-----
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6b13492..44ff0a3 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,20 @@
+# Preserves
+
 Nim implementation of the [Preserves data language](https://preserves.gitlab.io/preserves/preserves.html).
 
+## Library
+
+To parse or produce Preserves one should write a
+[schema](https://preserves.gitlab.io/preserves/preserves-schema.html) and
+generate a Nim module using the `preserves_schema_nim` utility. This module will
+contain Nim types corresponding to schema definitions. The `toPreserve` and
+`fromPreserve` routines will convert Nim types to and from Preserves. The
+`decodePreserves`, `parsePreserves`, `encode`, and `$` routines will convert
+`Preserve` objects to and from binary and textual encoding.
+
+To debug the `toPreserves` and `fromPreserves` routines compile with
+`-d:tracePreserves`.
+
 ## Utilities
 * preserves_schema_nim
 * preserves_encode
@@ -7,7 +22,7 @@ Nim implementation of the [Preserves data language](https://preserves.gitlab.io/
 * preserves_from_json
 * preserves_to_json
 
-## Installation
+### Installation
 `preserves_encode` is a multi-call binary that implements `preserves_encode`,
 `preserves_decode`, `preserves_from_json`, and `preserves_to_json`, so the
 appropriate symlinks should be created during packaging.
diff --git a/src/preserves.nim b/src/preserves.nim
index e10a69d..4ac8750 100644
--- a/src/preserves.nim
+++ b/src/preserves.nim
@@ -25,7 +25,7 @@ const
   compoundKinds* = {pkRecord, pkSequence, pkSet, pkDictionary}
 
 type
-  Preserve*[E = void] {.acyclic.} = object
+  Preserve*[E = void] = object
     case kind*: PreserveKind
     of pkBoolean:
       bool*: bool
@@ -104,7 +104,7 @@ proc `<`(x, y: string | seq[byte]): bool =
   x.len < y.len
 
 proc `<`*[A, B](x: Preserve[A]; y: Preserve[B]): bool =
-  ## Preserves have a total order over Values. Check if `x` is ordered before `y`.
+  ## Preserves have a total order over values. Check if `x` is ordered before `y`.
   if x.embedded != y.embedded:
     result = y.embedded
   elif x.kind != y.kind:
@@ -323,7 +323,7 @@ iterator items*(pr: Preserve): Preserve =
 func isBoolean*(pr: Preserve): bool {.inline.} = pr.kind == pkBoolean
   ## Check if ``pr`` is a Preserve boolean.
 
-func isFalse*(pr: Preserve): bool =
+func isFalse*(pr: Preserve): bool {.inline.} =
   ## Check if ``pr`` is equivalent to the zero-initialized ``Preserve``.
   pr.kind == pkBoolean and pr.bool == false
 
@@ -646,6 +646,9 @@ proc toPreserve*[T](x: T; E = void): Preserve[E] =
   ## ``toPreserveHook(x: T; E: typedesc)`` in the calling scope.
   ## Any ``toPreserveHook`` that does not compile will be discarded;
   ## *Write tests for your hooks!*
+  ##
+  ## When `tracePreserves` is defined (`-d:tracePreserves`) a diagnostic
+  ## trace is printing during `toPreserve`.
   when (T is Preserve[E]): result = x
   elif T is E: result = embed(x)
   elif compiles(toPreserveHook(x, E)):
@@ -764,10 +767,13 @@ proc fromPreserve*[T, E](v: var T; pr: Preserve[E]): bool =
   ## Can be customized with `fromPreserveHook[E](x: T; var pr: Preserve[E]): bool`.
   ## Any ``fromPreserveHook`` that does not compile will be discarded;
   ## *Write tests for your hooks!*
+  ##
+  ## When `tracePreserves` is defined (`-d:tracePreserves`) a diagnostic
+  ## trace is printing during `fromPreserve`.
   # TODO: {.raises: [].}
   runnableExamples:
     import preserves, preserves/parse
-    type Foo {.record: "foo".} = object
+    type Foo {.preservesRecord: "foo".} = object
       x, y: int
     var foo: Foo
     assert(fromPreserve(foo, parsePreserves("""<foo 1 2>""")))
@@ -944,7 +950,7 @@ proc preserveTo*(pr: Preserve; T: typedesc): Option[T] =
   # TODO: {.raises: [].}
   runnableExamples:
     import std/options, preserves, preserves/parse
-    type Foo {.record: "foo".} = object
+    type Foo {.preservesRecord: "foo".} = object
       x, y: int
 
     assert(parsePreserves("""<foo "abc">""").preserveTo(Foo).isNone)