From 23bee1117e913d713a001f651a08db6a83c72c71 Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Thu, 5 Oct 2023 14:52:54 -0700 Subject: [PATCH] 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 | 12 ++++++------ library/classes.lisp | 40 ++++++++++++++++++++-------------------- library/functions.lisp | 12 ++++++------ library/hash.lisp | 2 +- library/list.lisp | 14 ++++++-------- library/math/arith.lisp | 6 +++--- 6 files changed, 42 insertions(+), 44 deletions(-) diff --git a/library/builtin.lisp b/library/builtin.lisp index fd3f8064b..d339446d2 100644 --- a/library/builtin.lisp +++ b/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)))) diff --git a/library/classes.lisp b/library/classes.lisp index 2303541f6..2a98b8b70 100644 --- a/library/classes.lisp +++ b/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,12 +233,12 @@ (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)) ;; @@ -246,7 +246,7 @@ ;; (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))) diff --git a/library/functions.lisp b/library/functions.lisp index 2a9cc7fca..beb6fdcfe 100644 --- a/library/functions.lisp +++ b/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))) ;; diff --git a/library/hash.lisp b/library/hash.lisp index 9af570ca8..6e743f9fb 100644 --- a/library/hash.lisp +++ 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)) diff --git a/library/list.lisp b/library/list.lisp index bb8cf99b5..0c7321950 100644 --- a/library/list.lisp +++ b/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) diff --git a/library/math/arith.lisp b/library/math/arith.lisp index c20efaf2b..3c9a308e0 100644 --- a/library/math/arith.lisp +++ b/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)