improve typesetting of some docstrings

This commit mostly fixes a few little docs bugs, and tries
to be more uniform in the use of `x` over X.

library/builtin.lisp

@@ -31,37 +31,37 @@
     (error "Undefined"))
 
   (define not
-    "Synonym for BOOLEAN-NOT."
+    "Synonym for `boolean-not`."
     boolean-not)
 
   (define xor
-    "Synonym for BOOLEAN-XOR."
+    "Synonym for `boolean-xor`."
     boolean-xor)
 
   (declare boolean-not (Boolean -> Boolean))
   (define (boolean-not x)
-    "Is X False?"
+    "The logical negation of `x`. Is `x` false?"
     (match x
       ((True) False)
       ((False) True)))
 
   (declare boolean-or (Boolean -> Boolean -> Boolean))
   (define (boolean-or x y)
-    "Is X or Y True? Note that this is a *function* which means both X and Y will be evaluated. Use the OR macro for short-circuiting behavior."
+    "Is either `x` or `y` true? Note that this is a *function* which means both `x` and `y` will be evaluated. Use the `or` macro for short-circuiting behavior."
     (match x
       ((True) True)
       ((False) y)))
 
   (declare boolean-and (Boolean -> Boolean -> Boolean))
   (define (boolean-and x y)
-    "Are X and Y True? Note that this is a *function* which means both X and Y will be evaluated. Use the AND macro for short-circuiting behavior."
+    "Are both `x` and `y` true? Note that this is a *function* which means both `x` and `y` will be evaluated. Use the AND macro for short-circuiting behavior."
     (match x
       ((True) y)
       ((False) False)))
 
   (declare boolean-xor (Boolean -> Boolean -> Boolean))
   (define (boolean-xor x y)
-    "Are X or Y True, but not both?"
+    "Are `x` or `y` true, but not both?"
     (match x
       ((True) (boolean-not y))
       ((False) y))))

library/classes.lisp

@@ -130,42 +130,42 @@
 
   (declare > (Ord :a => :a -> :a -> Boolean))
   (define (> x y)
-    "Is X greater than Y?"
+    "Is `x` greater than `y`?"
     (match (<=> x y)
       ((GT) True)
       (_ False)))
 
   (declare < (Ord :a => :a -> :a -> Boolean))
   (define (< x y)
-    "Is X less than Y?"
+    "Is `x` less than `y`?"
     (match (<=> x y)
       ((LT) True)
       (_ False)))
 
   (declare >= (Ord :a => :a -> :a -> Boolean))
   (define (>= x y)
-    "Is X greater than or equal to Y?"
+    "Is `x` greater than or equal to `y`?"
     (match (<=> x y)
       ((LT) False)
       (_ True)))
 
   (declare <= (Ord :a => :a -> :a -> Boolean))
   (define (<= x y)
-    "Is X less than or equal to Y?"
+    "Is `x` less than or equal to `y`?"
     (match (<=> x y)
       ((GT) False)
       (_ True)))
 
   (declare max (Ord :a => :a -> :a -> :a))
   (define (max x y)
-    "Returns the greater element of X and Y."
+    "Returns the greater element of `x` and `y`."
     (if (> x y)
         x
         y))
 
   (declare min (Ord :a => :a -> :a -> :a))
   (define (min x y)
-    "Returns the lesser element of X and Y."
+    "Returns the lesser element of `x` and `y`."
     (if (< x y)
         x
         y))
@@ -210,9 +210,9 @@
   (define-class (Foldable :container)
     "Types which can be folded into a single element.
 
-`fold` is a left tail recursive fold
+`fold` is a left tail recursive fold.
 
-`foldr` is a right non tail recursive fold"
+`foldr` is a right non tail recursive fold."
     (fold ((:accum -> :elt -> :accum) -> :accum -> :container :elt -> :accum))
     (foldr ((:elt -> :accum -> :accum) -> :accum -> :container :elt -> :accum)))
 
@@ -233,20 +233,20 @@
 
   (declare map-fst (Bifunctor :f => (:a -> :b) -> :f :a :c -> :f :b :c))
   (define (map-fst f b)
-    "Map over the first argument of a Bifunctor."
+    "Map over the first argument of a `Bifunctor`."
     (bimap f (fn (x) x) b))
 
   (declare map-snd (Bifunctor :f => (:b -> :c) -> :f :a :b -> :f :a :c))
   (define (map-snd f b)
-    "Map over the second argument of a Bifunctor."
+    "Map over the second argument of a `Bifunctor`."
     (bimap (fn (x) x) f b))
 
   ;;
   ;; Conversions
   ;;
 
   (define-class (Into :a :b)
-    "INTO imples *every* element of :a can be represented by an element of :b. This conversion might not be bijective (i.e., there may be elements in :b that don't correspond to any in :a)."
+    "INTO imples *every* element of `:a` can be represented by an element of `:b`. This conversion might not be bijective (i.e., there may be elements in `:b` that don't correspond to any in `:a`)."
     (into (:a -> :b)))
 
   (define-class ((Into :a :b) (Into :b :a) => Iso :a :b)
@@ -275,12 +275,12 @@
   (define-class (Unwrappable :container)
     "Containers which can be unwrapped to get access to their contents.
 
-(unwrap-or-else SUCCEED FAIL CONTAINER) should invoke the SUCCEED continuation on the unwrapped contents of
-CONTAINER when successful, or invoke the FAIL continuation with no arguments (i.e. with Unit as an argument)
+`(unwrap-or-else succeed fail container)` should invoke the `succeed` continuation on the unwrapped contents of
+`container` when successful, or invoke the `fail` continuation with no arguments (i.e., with `Unit` as an argument)
 when unable to unwrap a value.
 
-The SUCCEED continuation will often, but not always, be the identity function. `as-optional` passes Some to
-construct an Optional.
+The `succeed` continuation will often, but not always, be the identity function. `as-optional` passes `Some` to
+construct an `Optional`.
 
 Typical `fail` continuations are:
 - Return a default value, or
@@ -295,7 +295,7 @@ Typical `fail` continuations are:
                    -> (:container :element)
                    -> :element))
   (define (expect reason container)
-    "Unwrap CONTAINER, signaling an error with the description REASON on failure."
+    "Unwrap `container`, signaling an error with the description `reason` on failure."
     (unwrap-or-else (fn (elt) elt)
                     (fn () (error reason))
                     container))
@@ -304,7 +304,7 @@ Typical `fail` continuations are:
                    (:container :element)
                    -> :element))
   (define (unwrap container)
-    "Unwrap CONTAINER, signaling an error on failure."
+    "Unwrap `container`, signaling an error on failure."
     (unwrap-or-else (fn (elt) elt)
                     (fn () (error (lisp String (container)
                                     (cl:format cl:nil "Unexpected ~a in UNWRAP"
@@ -316,14 +316,14 @@ Typical `fail` continuations are:
                          -> (:container :element)
                          -> :element))
   (define (with-default default container)
-    "Unwrap CONTAINER, returning DEFAULT on failure."
+    "Unwrap `container`, returning `default` on failure."
     (unwrap-or-else (fn (elt) elt)
                     (fn () default)
                     container))
 
   (declare as-optional ((Unwrappable :container) => (:container :elt) -> (Optional :elt)))
   (define (as-optional container)
-    "Convert any Unwrappable container into an Optional, constructing Some on a successful unwrap and None on a failed unwrap."
+    "Convert any Unwrappable container into an `Optional`, constructing Some on a successful unwrap and None on a failed unwrap."
     (unwrap-or-else Some
                     (fn () None)
                     container))
@@ -340,7 +340,7 @@ Typical `fail` continuations are:
   (declare defaulting-unwrap ((Unwrappable :container) (Default :element) =>
                               (:container :element) -> :element))
   (define (defaulting-unwrap container)
-    "Unwrap an UNWRAPPABLE, returning (DEFAULT) of the wrapped type on failure. "
+    "Unwrap an `unwrappable`, returning `(default)` of the wrapped type on failure. "
     (unwrap-or-else (fn (elt) elt)
                     (fn () (default))
                     container)))

library/functions.lisp

@@ -31,14 +31,14 @@
 (coalton-toplevel
   (declare trace (String -> Unit))
   (define (trace str)
-    "Print a line to `*STANDARD-OUTPUT*`"
+    "Print a line to `cl:*standard-output*`."
     (progn
       (lisp :a (str) (cl:format cl:t"~A~%" str))
       Unit))
 
   (declare traceObject (String -> :a -> Unit))
   (define (traceObject str item)
-    "Print a line to `*STANDARD-OUTPUT*` in the form \"{STR}: {ITEM}\""
+    "Print a line to `cl:*standard-output*` in the form \"{STR}: {ITEM}\"."
     (progn
       (lisp :a (str item) (cl:format cl:t "~A: ~A~%" str item))
       Unit))
@@ -90,7 +90,7 @@
   ;; considered to be "saturated".
   (declare compose ((:b -> :c) -> (:a -> :b) -> (:a -> :c)))
   (define (compose f g)
-    "Produces a function equivalent to applying G then F in succession."
+    "Produces a function equivalent to applying `g` followed by `f`."
     ;; Note: ((compose f g) x) behaves like (f (g x))
     (fn (x)
       (f (g x))))
@@ -122,17 +122,17 @@
 
   (declare msum ((Monoid :a) (Foldable :t) => :t :a -> :a))
   (define (msum xs)
-    "Fold over a list using <>"
+    "Fold over a list using `<>`."
     (foldr <> mempty xs))
 
   (declare asum ((Alternative :f) (Foldable :t) => :t (:f :a) -> :f :a))
   (define (asum xs)
-    "Fold over a list using alt"
+    "Fold over a list using `alt`."
     (foldr alt empty xs))
 
   (declare /= (Eq :a => :a -> :a -> Boolean))
   (define (/= a b)
-    "Is A not equal to B?"
+    "Is `a` not equal to `b`?"
     (boolean-not (== a b)))
 
   ;;

library/hash.lisp

@@ -34,7 +34,7 @@
   (define-class (Eq :a => Hash :a)
     "Types which can be hashed for storage in hash tables.
 
-Invariant (== left right) implies (== (hash left) (hash right))."
+The hash function must satisfy the invariant that `(== left right)` implies `(== (hash left) (hash right))`."
     (hash (:a -> Hash)))
 
   (declare combine-hashes (Hash -> Hash -> Hash))

library/list.lisp

@@ -267,14 +267,12 @@
   (define (range start end)
     "Returns a list containing the numbers from START to END inclusive, counting by 1.
 
-
-    ```
-    > COALTON-USER> (coalton (range 1 5))
+    COALTON-USER> (coalton (range 1 5))
     (1 2 3 4 5)
 
-    > COALTON-USER> (coalton (range 5 2))
+    COALTON-USER> (coalton (range 5 2))
     (5 4 3 2)
-    ```"
+"
     (let ((inner (fn (x end a)
                    (if (> x end)
                        a
@@ -381,17 +379,17 @@
 
   (declare remove (Eq :a => (:a -> (List :a) -> (List :a))))
   (define (remove x ys)
-    "Return a new list with the first element equal to X removed."
+    "Return a new list with the first element equal to `x` removed."
     (remove-if (== x) ys))
 
   (declare difference (Eq :a => ((List :a) -> (List :a) -> (List :a))))
   (define (difference xs ys)
-    "Returns a new list with the first occurence of each element in YS removed from XS."
+    "Returns a new list with the first occurence of each element in `ys` removed from `xs`."
     (fold (fn (a b) (remove b a)) xs ys))
 
   (declare zipWith ((:a -> :b -> :c) -> (List :a) -> (List :b) -> (List :c)))
   (define (zipWith f xs ys)
-    "Builds a new list by calling F with elements of XS and YS."
+    "Builds a new list by calling `f` with elements of `xs` and `ys`."
     (let ((rec
             (fn (xs ys acc)
               (match (Tuple xs ys)

library/math/arith.lisp

@@ -56,7 +56,7 @@
     (/ x y) = (* x (reciprocal y))
 
 
-If no reciprocal exists for an element, produce a run-time error (e.g. zero).
+If no reciprocal exists for an element, produce a run-time error (e.g., zero).
 "
     (/ (:a -> :a -> :a))
     (reciprocal (:a -> :a)))
@@ -78,7 +78,7 @@ establishes that division of two `Single-Float`s can result in a `Single-Float`.
 
 Note that `Dividable` does *not* establish a default result type; you must constrain the result type yourself.
 
-The function general/ is partial, and will error produce a run-time error if the divisor is zero.
+The function `general/` is partial, and will error produce a run-time error if the divisor is zero.
 "
     ;; This is a type that is more pragmatic and less mathematical in
     ;; nature. It expresses a division relationship between one input
@@ -89,7 +89,7 @@ The function general/ is partial, and will error produce a run-time error if the
     (define (general/ a b) (/ a b)))
 
   (define-class (Transfinite :a)
-    "Numeric type with a value for (positive) 'infinity' and/or 'NaN'"
+    "Numeric type with a value for (positive) infinity and/or NaN."
     (infinity :a)
     (infinite? (:a -> Boolean))
     (nan :a)