additional documentation and formatting tweaks

disco-lang · Dec 25, 2024 · 9ec3a50 · 9ec3a50
1 parent 71bef60
commit 9ec3a50
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 48 deletions.
diff --git a/docs/reference/compare.rst b/docs/reference/compare.rst
@@ -68,3 +68,9 @@ many.
   as combining all the individual comparisons with "and".  For
   example, ``3 <= x < y <= 10`` means the same thing as ``3 <= x /\ x
   < y /\ y <= 10``.
+
+* The ``max`` and ``min`` functions can be used on any type which
+  supports comparison.  ``max`` takes two arguments and returns
+  whichever one is larger; ``min`` is similar but returns the smaller
+  argument. For example, ``max(3,6)`` and ``max(6,3)`` both evaluate
+  to ``6``.
diff --git a/src/Disco/Doc.hs b/src/Disco/Doc.hs
@@ -65,40 +65,40 @@ docMap =
       [mkIntro "arithmetic", mkRef "subtraction"]
     , PrimKey (PrimBOp SSub) ==>
       "The difference of two numbers, with a lower bound of 0." ==>
-      [mkRef "subtraction"]
+      [mkIntro "arithmetic", mkRef "subtraction"]
     , PrimKey (PrimBOp Mul) ==>
       "The product of two numbers, types, or graphs." ==>
-      [mkRef "multiplication"]
+      [mkIntro "arithmetic", mkRef "multiplication"]
     , PrimKey (PrimBOp Div) ==>
       "Divide two numbers." ==>
-      [mkRef "division"]
+      [mkIntro "arithmetic", mkRef "division"]
     , PrimKey (PrimBOp IDiv) ==>
       "The integer quotient of two numbers, rounded down." ==>
-      [mkRef "integerdiv"]
+      [mkIntro "arithmetic", mkRef "integerdiv"]
     , PrimKey (PrimBOp Mod) ==>
       "a mod b is the remainder when a is divided by b." ==>
       [mkRef "mod"]
     , PrimKey (PrimBOp Exp) ==>
       "Exponentiation.  a ^ b is a raised to the b power." ==>
-      [mkRef "exponentiation"]
+      [mkIntro "arithmetic", mkRef "exponentiation"]
     , PrimKey (PrimUOp Fact) ==>
       "n! computes the factorial of n, that is, 1 * 2 * ... * n." ==>
       [mkRef "factorial"]
-    , PrimKey (PrimFloor) ==>
+    , PrimKey PrimFloor ==>
       "floor(x) is the largest integer which is <= x." ==>
-      [mkRef "round"]
-    , PrimKey (PrimCeil) ==>
+      [mkIntro "arithmetic", mkRef "round"]
+    , PrimKey PrimCeil ==>
       "ceiling(x) is the smallest integer which is >= x." ==>
-      [mkRef "round"]
-    , PrimKey (PrimAbs) ==>
-      "abs(x) is the absolute value of x.  Also written |x|." ==>
-      [mkRef "abs"]
-    , PrimKey (PrimMin) ==>
+      [mkIntro "arithmetic", mkRef "round"]
+    , PrimKey PrimAbs ==>
+      "abs(x) is the absolute value of x." ==>
+      [mkIntro "arithmetic", mkRef "abs"]
+    , PrimKey PrimMin ==>
       "min(x,y) is the minimum of x and y, i.e. whichever is smaller." ==>
-      []
-    , PrimKey (PrimMax) ==>
+      [mkRef "compare"]
+    , PrimKey PrimMax ==>
       "max(x,y) is the maximum of x and y, i.e. whichever is larger." ==>
-      []
+      [mkRef "compare"]
     , PrimKey (PrimUOp Not) ==>
       "Logical negation: not(T) = F and not(F) = T." ==>
       [mkRef "logic-ops"]
@@ -149,49 +149,49 @@ docMap =
       [mkRef "set-ops"]
     , OtherKey "N" ==>
       docN ==>
-      [mkRef "natural"]
+      [mkIntro "types", mkRef "natural"]
     , OtherKey "ℕ" ==>
       docN ==>
-      [mkRef "natural"]
+      [mkIntro "types", mkRef "natural"]
     , OtherKey "Nat" ==>
       docN ==>
-      [mkRef "natural"]
+      [mkIntro "types", mkRef "natural"]
     , OtherKey "Natural" ==>
       docN ==>
-      [mkRef "natural"]
+      [mkIntro "types", mkRef "natural"]
     , OtherKey "Z" ==>
       docZ ==>
-      [mkRef "integer"]
+      [mkIntro "types", mkRef "integer"]
     , OtherKey "ℤ" ==>
       docZ ==>
-      [mkRef "integer"]
+      [mkIntro "types", mkRef "integer"]
     , OtherKey "Int" ==>
       docZ ==>
-      [mkRef "integer"]
+      [mkIntro "types", mkRef "integer"]
     , OtherKey "Integer" ==>
       docZ ==>
-      [mkRef "integer"]
+      [mkIntro "types", mkRef "integer"]
     , OtherKey "F" ==>
       docF ==>
-      [mkRef "fraction"]
+      [mkIntro "types", mkRef "fraction"]
     , OtherKey "𝔽" ==>
       docF ==>
-      [mkRef "fraction"]
+      [mkIntro "types", mkRef "fraction"]
     , OtherKey "Frac" ==>
       docF ==>
-      [mkRef "fraction"]
+      [mkIntro "types", mkRef "fraction"]
     , OtherKey "Fractional" ==>
       docF ==>
-      [mkRef "fraction"]
+      [mkIntro "types", mkRef "fraction"]
     , OtherKey "Q" ==>
       docQ ==>
-      [mkRef "rational"]
+      [mkIntro "types", mkRef "rational"]
     , OtherKey "ℚ" ==>
       docQ ==>
-      [mkRef "rational"]
+      [mkIntro "types", mkRef "rational"]
     , OtherKey "Rational" ==>
       docQ ==>
-      [mkRef "rational"]
+      [mkIntro "types", mkRef "rational"]
     , OtherKey "Bool" ==>
       docB ==>
       [mkRef "bool"]
@@ -209,7 +209,7 @@ docMap =
       [mkRef "set"]
     , OtherKey "|~|" ==>
       "Absolute value, or the size of a collection." ==>
-      [mkRef "size"]
+      [mkIntro "arithmetic", mkRef "size"]
     , OtherKey "{?" ==>
       "{? ... ?} is a case expression, for choosing a result based on conditions." ==>
       [mkRef "case"]

diff --git a/src/Disco/Interactive/Commands.hs b/src/Disco/Interactive/Commands.hs
@@ -73,7 +73,7 @@ import Disco.Pretty qualified as PP
 import Disco.Property (prettyTestResult)
 import Disco.Syntax.Operators
 import Disco.Syntax.Prims (
-  Prim (PrimBOp, PrimUOp),
+  Prim (PrimBOp, PrimUOp, PrimFloor, PrimCeil, PrimAbs),
   toPrim,
  )
 import Disco.Typecheck
@@ -464,20 +464,26 @@ handleDocPrim ::
   Sem r ()
 handleDocPrim prim = do
   handleTypeCheck (TypeCheck (TPrim prim))
-  info
-    . vcat
-    $ ( case prim of
-          PrimUOp u -> describeAlts (f == Post) (f == Pre) syns
-           where
-            OpInfo (UOpF f _) syns _ = uopMap ! u
-          PrimBOp b -> describeAlts True True (opSyns $ bopMap ! b)
-          _ -> []
-      )
-      ++ ( case prim of
-            PrimUOp u -> [describePrec (uPrec u)]
-            PrimBOp b -> [describePrec (bPrec b) <> describeFixity (assoc b)]
+  let attrs =
+        ( case prim of
+            PrimUOp u -> describeAlts (f == Post) (f == Pre) syns
+             where
+              OpInfo (UOpF f _) syns _ = uopMap ! u
+            PrimBOp b -> describeAlts True True (opSyns $ bopMap ! b)
+            PrimFloor -> describeAlts False False ["floor(x)", "⌊x⌋"]
+            PrimCeil -> describeAlts False False ["ceiling(x)", "⌈x⌉"]
+            PrimAbs -> describeAlts False False ["abs(x)", "|x|"]
             _ -> []
-         )
+        )
+        ++ ( case prim of
+              PrimUOp u -> [describePrec (uPrec u)]
+              PrimBOp b -> [describePrec (bPrec b) <> describeFixity (assoc b)]
+              _ -> []
+           )
+  case attrs of
+    [] -> pure ()
+    _ -> info . vcat $ attrs
+  info PP.empty
   handleDocMap (PrimKey prim)
  where
   describePrec p = "precedence level" <+> text (show p)
@@ -511,8 +517,6 @@ handleDocMap k = case M.lookup k docMap of
     OtherKey s -> info $ "No documentation found for '" <> text s <> "'."
   Just (d, refs) ->
     info . vcat $
-      case k of { PrimKey {} -> [PP.empty]; _ -> [] }
-      ++
       [ text d
       , PP.empty
       ]