Code documentation

- Add description for `BranchStmA`
- Reword description about not handling the catch handler argument

Author: yogeshsajanikar

io-sim/src/Control/Monad/IOSim/Types.hs

@@ -895,10 +895,22 @@ data StmTxResult s a =
      | StmTxAborted  [SomeTVar s] SomeException
 
 
--- | A branch is an alternative of a `OrElse` or a `CatchStm` statement
-data BranchStmA s a = OrElseStmA (StmA s a)
-                    | CatchStmA (SomeException -> StmA s a)
-                    | NoOpStmA
+-- | A branch indicates an alternative statment available in the current context.
+-- For example, `OrElse` has two alternative statements, say "left" and "right".
+-- While executing the left statement, `OrElseStmA` branch indicates that the
+-- right branch is still available, in case, left statement fails.
+data BranchStmA s a =
+       -- | `OrElse` statement with its 'right' alternative.
+       OrElseStmA (StmA s a)
+       -- | `CatchStm` statment with 'catch' handler.
+     | CatchStmA (SomeException -> StmA s a)
+       -- | No op statment is not a part of the STM semantics. It simply
+       -- indicates that there are no alternative statements left to be executed.
+       -- For example, when running right alternative of the `OrElse` statement
+       -- or when running the catch handler of a `CatchStm` statement, there are
+       -- alternative statements available. This case is represented by no-op
+       -- branch.
+     | NoOpStmA
 
 data StmStack s b a where
   -- | Executing in the context of a top level 'atomically'.

io-sim/test/Test/STM.hs

@@ -319,7 +319,7 @@ evalTerm !env !heap !allocs term = case term of
         -- Rule XSTM1
         --                M; heap, {} => return P; heap', allocs'
         -- --------------------------------------------------------
-        -- S[catch M N]; heap, allocs => S[return P]; heap', allocs'
+        -- S[catch M N]; heap, allocs => S[return P]; heap', allocs U allocs'
         NfReturn v -> (NfReturn v, heap', allocs <> allocs')
 
         -- Rule XSTM2
@@ -771,10 +771,8 @@ shrinkExpr (ExprName (Name _ (TyRepVar _))) = []
 freeNamesTerm :: Term t -> Set NameId
 freeNamesTerm (Return e)      = freeNamesExpr e
 freeNamesTerm (Throw  e)      = freeNamesExpr e
--- A catch handler should actually have an argument, and then the implementation
--- should handle it. But since current implementation of catch never binds the
--- variable, the following implementation is correct as of now. It needs to be
--- tackled once nested exceptions are handled.
+-- The current generator of catch term ignores the argument passed to the
+-- handler.
 -- TODO: Correctly handle free names when the handler also binds a variable.
 freeNamesTerm (Catch t1 t2)   = freeNamesTerm t1 <> freeNamesTerm t2
 freeNamesTerm  Retry          = Set.empty