Skip to content

Commit

Permalink
improve typesetting of some docstrings
Browse files Browse the repository at this point in the history
This commit mostly fixes a few little docs bugs, and tries
to be more uniform in the use of `x` over X.
  • Loading branch information
stylewarning committed Oct 5, 2023
1 parent 88ba669 commit 23bee11
Show file tree
Hide file tree
Showing 6 changed files with 42 additions and 44 deletions.
12 changes: 6 additions & 6 deletions library/builtin.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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))))
Expand Down
40 changes: 20 additions & 20 deletions library/classes.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down Expand Up @@ -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)))

Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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))
Expand All @@ -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"
Expand All @@ -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))
Expand All @@ -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)))
Expand Down
12 changes: 6 additions & 6 deletions library/functions.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down Expand Up @@ -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))))
Expand Down Expand Up @@ -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)))

;;
Expand Down
2 changes: 1 addition & 1 deletion library/hash.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
14 changes: 6 additions & 8 deletions library/list.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
6 changes: 3 additions & 3 deletions library/math/arith.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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)))
Expand All @@ -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
Expand All @@ -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)
Expand Down

0 comments on commit 23bee11

Please sign in to comment.