Move CallStack, HasCallStack docs to DA.Stack (#7735)

* Move CallStack, HasCallStack docs to DA.Stack This PR only modifies the docs. In particular, it: - moves the `CallStack` and `HasCallStack` docs to `DA.Stack` - gives an example of adding the `HasCallStack` constraint - hides the rest of `GHC.Stack.Types` from the docs Rationale: `GHC.Stack.Types` has a lot of `TextLit` stuff that we don't want people to use directly, and we want people to import `DA.Stack` instead anyway. changelog_begin changelog_end * commit unsaved changes, doh * grammar
digital-asset · Oct 19, 2020 · 5e0559c · 5e0559c
1 parent 5f0acbc
commit 5e0559c
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 14 deletions.
diff --git a/compiler/damlc/daml-prim-src/GHC/Stack/Types.daml b/compiler/damlc/daml-prim-src/GHC/Stack/Types.daml
@@ -3,6 +3,8 @@
 
 {-# LANGUAGE ImplicitParams #-}
 {-# LANGUAGE NoImplicitPrelude #-}
+
+-- | MOVE DA.Stack
 module GHC.Stack.Types where
 
 import GHC.Classes ()
@@ -11,42 +13,60 @@ import GHC.Err
 import GHC.Tuple ()
 import GHC.Types
 
--- | Request a CallStack.
+-- | Request a `CallStack`. Use this as a constraint in type signatures in order
+-- to get nicer callstacks for error and debug messages.
+--
+-- For example, instead of declaring the following type signature:
+--
+-- ```
+-- myFunction : Int -> Update ()
+-- ```
 --
--- Calls to functions with this constraint will be added to the callstack.
--- You can get access to the current call stack with `callStack`.
+-- You can declare a type signature with the `HasCallStack` constraint:
 --
--- Note that if the call stack is reset if any function in between does not
--- have a `HasCallStack` constraint.
+-- ```
+-- myFunction : HasCallStack => Int -> Update ()
+-- ```
+--
+-- The function `myFunction` will still be called the same way, but it will also show up
+-- as an entry in the current callstack, which you can obtain with `callStack`.
+--
+-- Note that only functions with the `HasCallStack` constraint will be added to the
+-- current callstack, and if any function does not have the `HasCallStack` constraint,
+-- the callstack will be reset within that function.
 type HasCallStack = (?callStack : CallStack)
 
 -- NOTE (MK): Note that everything in this module
 -- needs to use `TextLit`. Otherwise, you will get core linting errors
 -- due to mismatch between TextLit and Text.
 
--- | Type of `CallStack`s constructed automatically from `HasCallStack` constraints.
+-- | Type of callstacks constructed automatically from `HasCallStack` constraints.
 --
--- Use `getCallStack` to deconstruct the `CallStack`.
+-- Use `callStack` to get the current callstack, and use `getCallStack`
+-- to deconstruct the `CallStack`.
 data CallStack
-  = EmptyCallStack
-  | PushCallStack (TextLit, SrcLoc, CallStack)
-  | FreezeCallStack CallStack
+  = EmptyCallStack -- ^ HIDE
+  | PushCallStack (TextLit, SrcLoc, CallStack) -- ^ HIDE
+  | FreezeCallStack CallStack -- ^ HIDE
 
+-- | HIDE
 emptyCallStack : CallStack
 emptyCallStack = EmptyCallStack
 
+-- | HIDE
 pushCallStack : (TextLit, SrcLoc) -> CallStack -> CallStack
 pushCallStack (fn, loc) stk = case stk of
   FreezeCallStack _ -> stk
   _                 -> PushCallStack (fn, loc, stk)
 
+-- | HIDE
 popCallStack : CallStack -> CallStack
 popCallStack stk = case stk of
   EmptyCallStack         -> error "popCallStack: empty stack"
   PushCallStack (_, _, stk') -> stk'
   FreezeCallStack _      -> stk
 
--- | Location in the source code.
+-- | HIDE Location in the source code.
 --
 -- Line and column are 1-based.
 data SrcLoc = SrcLoc
@@ -58,4 +78,3 @@ data SrcLoc = SrcLoc
   , srcLocEndLine   : Int
   , srcLocEndCol    : Int
   }
-
diff --git a/compiler/damlc/daml-stdlib-src/DA/Stack.daml b/compiler/damlc/daml-stdlib-src/DA/Stack.daml
@@ -16,7 +16,7 @@ import DA.Text
 import GHC.Stack.Types hiding (SrcLoc(..))
 import qualified GHC.Stack.Types as GHC
 
--- Pretty-print a `CallStack`.
+-- | Pretty-print a `CallStack`.
 prettyCallStack : CallStack -> Text
 prettyCallStack = intercalate "\n" . prettyCallStackLines
 
@@ -78,4 +78,3 @@ convSrcLoc GHC.SrcLoc{..} =
     , srcLocEndLine = srcLocEndLine - 1
     , srcLocEndCol = srcLocEndCol - 1
     }
-