Improve documentation

Author: willtebbutt

src/copyable_task.jl

@@ -41,7 +41,7 @@ end
 
 mutable struct TapedTask{Tdynamic_scope,Tfargs,Tmc<:MistyClosure}
     dynamic_scope::Tdynamic_scope
-    fargs::Tfargs
+    const fargs::Tfargs
     const mc::Tmc
     const position::Base.RefValue{Int32}
 end
@@ -369,7 +369,7 @@ function derive_copyable_task_ir(ir::BBCode)::Tuple{BBCode,Tuple}
         end
     end
 
-    # For each existing basic block, produce a sequence of `NamedTuple`s which
+    # For each existing basic block, create a sequence of `NamedTuple`s which
     # define the manner in which it must be split.
     # A block will in general be split as follows:
     # 1 - %1 = φ(...)
@@ -666,6 +666,16 @@ function derive_copyable_task_ir(ir::BBCode)::Tuple{BBCode,Tuple}
                 end
                 push!(new_blocks, BBlock(splits_ids[n], inst_pairs))
             elseif is_produce_stmt(stmt)
+                # This is a statement of the form
+                # %n = produce(arg)
+                #
+                # We transform this into
+                # Libtask.set_resume_block!(refs_id, id_of_next_block)
+                # return ProducedValue(arg)
+                #
+                # The point is to ensure that, next time that this `TapedTask` is called,
+                # computation is resumed from the statement _after_ this produce statement,
+                # and to return whatever this produce statement returns.
 
                 # When this TapedTask is next called, we should resume from the first
                 # statement of the next split.
@@ -699,7 +709,29 @@ function derive_copyable_task_ir(ir::BBCode)::Tuple{BBCode,Tuple}
                 push!(new_blocks, BBlock(splits_ids[n], inst_pairs))
             else
                 # The final statement is one which might produce, but is not itself a
-                # `produce` statement.
+                # `produce` statement. For example
+                # y = f(x)
+                #
+                # becomes (morally speaking)
+                # y = f(x)
+                # if y isa ProducedValue
+                #   set_resume_block!(refs_id, id_of_current_block)
+                #   return y
+                # end
+                #
+                # The point is to ensure that, if `f` "produces" (as indicated by `y` being
+                # a `ProducedValue`) then the next time that this TapedTask is called, we
+                # must resume from the call to `f`, as subsequent runs might also produce.
+                # On the other hand, if anything other than a `ProducedValue` is returned,
+                # we know that `f` has nothing else to produce, and execution can safely
+                # continue to the next split.
+                # In addition to the above, we must do the usual thing and ensure that any
+                # ssas are read from storage, and write the result of this computation to
+                # storage before continuing to the next instruction.
+                #
+                # You should look at the IR generated by a simple example in the test suite
+                # which involves calls that might produce, in order to get a sense of what
+                # the resulting code looks like prior to digging into the code below.
 
                 # Create a new basic block from the existing statements, since all new
                 # statement need to live in their own basic blocks.