From 11ff03a8113580244ced04a8b370ab6192b8e413 Mon Sep 17 00:00:00 2001
From: Nadrieril
Date: Fri, 22 Jan 2021 19:11:23 +0000
Subject: doc: document the `dhall` usage test

---
 dhall/README.md     |  5 +++--
 dhall/tests/misc.rs | 18 +++++++++++++++---
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/dhall/README.md b/dhall/README.md
index 25f11f7..071aecb 100644
--- a/dhall/README.md
+++ b/dhall/README.md
@@ -5,7 +5,8 @@ Implementation of the Dhall configuration language.
 WARNING: This is an internal crate used for [`serde_dhall`], you probably want
 to use that instead.
 
-WARNING: The API is very unstable and does not respect semver; use at your own
-risk.
+WARNING: The API is very unstable and does not respect semver; use at your own risk. If you want to
+use this crate directly anyways, have a look at [these tests].
 
+[these tests]: dhall/tests/misc.rs
 [`serde_dhall`]: https://docs.rs/serde_dhall
diff --git a/dhall/tests/misc.rs b/dhall/tests/misc.rs
index 3eecf03..4d80f53 100644
--- a/dhall/tests/misc.rs
+++ b/dhall/tests/misc.rs
@@ -10,29 +10,41 @@ use dhall::*;
 fn manual_function_application() {
     /// Apply a `Natural -> Natural` function to an argument.
     fn apply_natnat_fn<'cx>(f: &Nir<'cx>, n: u64) -> u64 {
+        // Convert the number to the internal representation.
         let n_nir = Nir::from_kind(NirKind::Num(NumKind::Natural(n)));
-        match f.app(n_nir).kind() {
+        // Apply `f` to `n`.
+        let m_nir = f.app(n_nir);
+        // Convert from the internal representation.
+        match m_nir.kind() {
             NirKind::Num(NumKind::Natural(m)) => *m,
             _ => panic!("`f` was not `Natural -> Natural`"),
         }
     }
+
     /// Auxiliary function to make `?` work.
-    fn run<'cx>(cx: Ctxt<'cx>) -> Result<(), Error> {
+    fn run(cx: Ctxt<'_>) -> Result<(), Error> {
+        // Parse the type we want into the internal representation.
         let f_ty = "Natural -> Natural";
-        let f = "\\(x: Natural) -> x + 3";
         let f_ty = Parsed::parse_str(f_ty)?
             .skip_resolve(cx)?
             .typecheck(cx)?
             .normalize(cx);
+
+        // Parse the function `f` itself, and also check its type.
+        let f = "\\(x: Natural) -> x + 3";
         let f = Parsed::parse_str(f)?
             .skip_resolve(cx)?
             .typecheck_with(cx, &f_ty.to_hir())?
             .normalize(cx);
+
+        // Do whatever we want with `f`.
         for i in 0..5 {
             let n = apply_natnat_fn(f.as_nir(), i);
             assert_eq!(n, i + 3);
         }
         Ok(())
     }
+
+    // The crate uses essentially a global context, created here.
     Ctxt::with_new(run).unwrap();
 }
-- 
cgit v1.2.3