Clarify Reactor arguments syntax. Change-Id: I081fd1bf7334d8a2209b467f053b123a27627c27 Reviewed-on: https://swiftshader-review.googlesource.com/5650 Reviewed-by: Nicolas Capens <capn@google.com> Tested-by: Nicolas Capens <capn@google.com>

diff --git a/docs/Reactor.md b/docs/Reactor.md
index 4eeb193..cbeec68 100644
--- a/docs/Reactor.md
+++ b/docs/Reactor.md

@@ -58,13 +58,13 @@
 

 The braces are superfluous. They just make the syntax look more like regular C++, and they offer a new scope for Reactor variables.

 

-The Routine is obtained and materialized by "calling" the Function<> object to give it a name:

+The Routine is obtained and materialized by "calling" the ```Function<>``` object to give it a name:

 

 ```C++

 Routine *routine = function(L"one");

 ```

 

-Next we can obtain the function pointer to the entry point of the routine, and call it:

+Finally, we can obtain the function pointer to the entry point of the routine, and call it:

 

 ```C++

 int (*callable)() = (int(*)())function.getEntry();

@@ -73,9 +73,11 @@
 assert(result == 1);

 ```

 

+Note that ```Function<>``` objects are relatively heavyweight, since they have the entire JIT-compiler behind them, while ```Routine``` objects are lightweight and merely provide storage and lifetime management of generated routines. So we typically allow the ```Function<>``` object to be destroyed (by going out of scope), while the ```Routine``` object is retained until we no longer need to call the routine. Hence the distinction between then and the need for a couple of lines of boilerplate code.

+

 ### Arguments and Expressions

 

-Routines can take various arguments that can be accessed using the following syntax:

+Routines can take various arguments. The following example illustrates the syntax for accessing the arguments of a routine which takes two integer arguments and returns their sum:

 

 ```C++

 Function<Int(Int, Int)> function;

@@ -89,8 +91,6 @@
 }

 ```

 

-This generates a routine which takes two integer arguments and returns their sum.

-

 Reactor supports various types which correspond to C++ types:

 

 | Class name    | C++ equivalent |

@@ -109,7 +109,7 @@
 

 These scalar types support all of the C++ arithmetic operations.

 

-Reactor also supports several vector types. For example Float4 is a vector of four floats. They support a select number of C++ operators, and several "intrinsic" functions such as ```Max()``` to compute the element-wise maximum and return a bit mask. Check [Nucleus.hpp](../src/Reactor/Nucleus.hpp) for all the types, operators and intrinsics.

+Reactor also supports several vector types. For example ```Float4``` is a vector of four floats. They support a select number of C++ operators, and several "intrinsic" functions such as ```Max()``` to compute the element-wise maximum and return a bit mask. Check [Nucleus.hpp](../src/Reactor/Nucleus.hpp) for all the types, operators and intrinsics.

 

 ### Casting and Reinterpreting