Text tweaks (#4014)

* Text tweaks

* No "of course"

Author: cuihtlauac

jane/doc/extensions/_01-stack-allocation/intro.md

@@ -18,7 +18,7 @@ and so they're safe to use in low-latency code that must currently be
 zero-alloc.
 
 Because of these advantages, values are allocated on a stack whenever
-possible. Of course, not all values can be allocated on a stack: a value that is
+possible. Not all values can be allocated on a stack: a value that is
 used beyond the scope of its introduction must be on the heap. Accordingly,
 the compiler uses the _locality_ of a value to determine where it will be
 allocated: _local_ values go on the stack, while _global_ ones must go on the
@@ -76,7 +76,7 @@ let f (local_ x) = ...
 ```
 
 A local parameter is a promise by a function not to let a particular
-argument escape its region. In the body of f, you'll get a type error
+argument escape the region where it belongs. In the body of f, you'll get a type error
 if x escapes, but when calling f you can freely pass stack-allocated values as
 the argument. This promise is visible in the type of f:
 

jane/doc/extensions/_01-stack-allocation/reference.md

@@ -13,8 +13,8 @@ The stack allocations language extension allows the compiler to
 stack-allocate some values, placing them on a stack rather than the
 garbage collected heap. Instead of waiting for the next GC, the memory
 used by stack-allocated values is reclaimed when their stack frame
-is reclaimed, and can be immediately reused. Whether the compiler
-stack-allocates certain values is controlled or inferred from new keywords
+is popped, and can be immediately reused. Whether the compiler
+stack-allocates certain values is inferred or controlled from new keywords
 `stack_` and `local_`, whose effects are explained below.
 
 ## Stack allocation
@@ -29,8 +29,8 @@ let abc = stack_ (42, 24) in
 
 Here, the tuple cell will be stack-allocated. The `stack_` keyword works shallowly: it
 only forces the immediately following allocation to be on stack. In the following
-example, the outer tuple is guaranteed to be on stack, while the inner one is not (
-although likely to be due to optimization).
+example, the outer tuple is guaranteed to be on stack, while the inner one is not
+(although likely to be due to optimization).
 ```ocaml
 let abc = stack_ (42, (24, 42)) in
 ...
@@ -61,17 +61,17 @@ including:
 
 At runtime, stack allocations do not take place on the function call stack, but on a
 separately-allocated stack that follows the same layout as the OCaml
-minor heap. In particular, this allows local-returning functions
-(see "Use `exclave_` to return a local value" below)
-without the need to copy returned values.
+minor heap. In particular, this enables local-returning functions
+without the need to copy returned values. See "Use `exclave_` to return a local value"
+below for more details.
 
 The runtime records the stack pointer when entering a new stack frame,
 and leaving that stack frame resets the stack pointer to that value.
 
 ## Regions
 
 Every stack allocation takes place inside a stack frame and is freed when the
-stack frame is freed. For this to be safe, stack-allocated values cannot be used
+stack frame is reclaimed. For this to be safe, stack-allocated values cannot be used
 after their stack frame is freed. This property is guaranteed at
 compile-time by the type checker as follows.
 
@@ -103,7 +103,7 @@ let l = if n > 0 then stack_ (n :: x) else x in
 ```
 
 Here, if `n > 0`, then `l` will be a stack-allocated cons cell and thus local.
-However, if `n <= 0`, then `l` will be `x`, which is global. The latter is
+However, if `n <= 0`, then `l` will be `x`, which is global. In that second case, `x` is
 implicitly weakened to local (because both branches of an `if` must have the
 same locality), making the whole
 expression local.
@@ -168,7 +168,8 @@ including an entire file. This region never ends and is where global (heap-alloc
 values live.
 
 One subtlety is that we wish to treat `local` variables from the current region
-differently than `local` variables from an enclosing region. The latter is called *outer-local*.
+differently than `local` variables from an enclosing region. Local from outside
+the current region is called *outer-local*.
 
 For instance:
 
@@ -183,16 +184,16 @@ let f () =
 ```
 
 At the point marked `??` inside `g`, both `outer` and `inner` are local values,
-but they live in different regions: `inner` lives in `g`'s region, while `outer`
-lives in the outer region and thus is outer-local.
+but they live in different regions: `inner` lives in the `g` region, while `outer`
+lives in the `f` region and thus is outer-local.
 
 So, if we replace `??` with `inner`, we see an error:
 
     Error: This local value escapes its region
 
 However, if we replace `??` with `outer`, the compiler will accept it: the
 value `outer`, while being local, was definitely not local to the region of
-`g`, and there is therefore no problem allowing it to escape `g`'s region.
+`g`, and there is therefore no problem allowing it to escape the `g` region.
 
 (This is quite subtle, and there is an additional wrinkle: how does the
 compiler know that it is safe to still refer to `outer` from within the closure
@@ -208,8 +209,8 @@ let f (local_ x) =
 
 Both `x` and `y` are local and cannot, in general, escape a region. However, filling `??`
 in with `x` (but not `y`) is allowed. This is because we know that `x` lives outside of
-`f`'s region and therefore will continue to exist after `f` ends. In contrast, `y` is a cons cell
-in `f`'s region, which will be destroyed after `f` ends.
+the `f` region and therefore will continue to exist after `f` ends. In contrast, `y` is a cons cell
+in the `f` region, which will be destroyed after `f` ends.
 
 ## Inference
 
@@ -317,8 +318,8 @@ which means it cannot be global. Therefore, it must be stack-allocated, and it
 local value `42 :: x` is not allowed to escape it.
 
 It is possible to write functions like `f3` that return stack-allocated
-values, but this requires an explicit annotation, as it would otherwise be easy to
-do by mistake.  See "Use `exclave_` to return a local value" below.
+values, but this requires an explicit annotation, as it could otherwise be done
+unintentionally.  See "Use `exclave_` to return a local value" below.
 
 Like local variables, inference can determine whether function arguments are
 local. However, note that for arguments of exported functions to be local, the
@@ -544,7 +545,7 @@ let make () = exclave_
 ```
 
 The keyword `exclave_` terminates the current region and executes the subsequent
-code in the outer region. Therefore, `ref 0` is executed in `f`'s region, which
+code in the outer region. Therefore, `ref 0` is executed in the `f` region, which
 allows its stack-allocation. The allocation will only be cleaned up when the
 region of `f` ends.
 
@@ -577,7 +578,7 @@ In this example, the function `f` has a region where the allocation for the
 complex computation occurs. This region is terminated by `exclave_`, releasing
 all temporary allocations. Both `None` and `Some x` are allocated in the
 caller's stack frame and are allowed to be returned. In summary, the
-temporary allocations in the `f`'s region are promptly released, and the result
+temporary allocations in the `f` region are promptly released, and the result
 allocated in the caller's region is returned.
 
 Here is another example in which the stack usage can be improved asymptotically
@@ -793,13 +794,13 @@ rejected:
 let local_ f : int -> int -> int = fun a b -> a + b + !counter in
 ...
 
-let f : int -> int -> int = stack_ fun a b -> a + b + !counter in
+let g : int -> int -> int = stack_ fun a b -> a + b + !counter in
 ...
 ```
 
 Both define a closure which accepts two integers and returns an integer. The
 closure must be local, since it refers to the local value `counter`. In the
-former definition, the type of the function appears under the `local_` keyword,
+definition of `f`, the type of the function appears under the `local_` keyword,
 and as described above is interpreted as:
 
 ```ocaml
@@ -808,8 +809,8 @@ int -> local_ (int -> int)
 
 This is the correct type for this function: if we partially apply it to
 a single argument, the resulting closure will still be local, as it refers to
-the original function which refers to `counter`. By contrast, in the latter
-definition the type of the function is outside the `stack_` keyword as is
+the original function which refers to `counter`. By contrast, in the
+definition of `g`, the type of the function is outside the `stack_` keyword as is
 interpreted as normal as:
 
 ```ocaml
@@ -822,7 +823,7 @@ case here. For this reason, this version is rejected. It would be accepted if
 written as follows:
 
 ```ocaml
-let f : int -> local_ (int -> int) = stack_ fun a b -> a + b + !counter in
+let g : int -> local_ (int -> int) = stack_ fun a b -> a + b + !counter in
 ...
 ```
 

jane/doc/extensions/_02-unboxed-types/intro.md

@@ -175,7 +175,7 @@ modules in the `janestreet_shims` library.)
 
 * With a few specific exceptions (documented below), existing types all expect
   `value` arguments. Thus for basically any `t`, you cannot write `float# t` or
-  `int64# t`.  This includes obvious candidates like `float#
+  `int64# t`.  This includes natural candidates like `float#
   option`.
 
 * Existing ppxs expect to work with `value` types. Accordingly, using `deriving` with

jane/doc/extensions/_04-modes/syntax.md

@@ -5,7 +5,7 @@ title: Syntax
 ---
 
 # Modes and modalities
-Currently a mode expression is simply a space-delimited list of modes.
+Currently a mode expression is a space-delimited list of modes.
 
 ```
 mode := local | global | unique | shared | many | once | portable | nonportable
@@ -24,7 +24,7 @@ Modes are in a dedicated namespace separated from variable names or type names,
 which means you can continue to use `local` or `unique` as variable or type
 names.
 
-Currently a modality expression is simply a space-delimited list of modalities.
+Currently a modality expression is a space-delimited list of modalities.
 
 ```
 modality := local | global | ..

jane/doc/extensions/_05-kinds/syntax.md

@@ -120,7 +120,7 @@ The abbreviations defined in the language are as follows:
       bound of `non_float` (because the value is not a pointer to a
       floating-point block).
 
-    Using `mod everything` is appropriate for simple data represented directly,
+    Using `mod everything` is appropriate for data represented directly,
     like `int` or `float32#`.
 
 * `any_non_null = any mod non_null`
@@ -227,7 +227,7 @@ still lower than both usages.
 The only question, then, is where to start the inference from? That is, what is
 default kind for a type parameter? It is tempting to say `any`, as that's the
 top. However, this would not be backward compatible, at least in module
-signatures, as we need the following very simple example to be accepted:
+signatures, as we need the following example to be accepted:
 
 ```ocaml
 module M : sig
@@ -376,7 +376,7 @@ val id : ('a : any). 'a -> 'a
 ```
 
 Here, we have annotated the binding site of `'a` to say that it should have kind
-`any`.  (The type `('a : any). 'a -> 'a` is a perfectly good type, and a
+`any`.  (The type `('a : any). 'a -> 'a` is valid, and a
 function of that type can be called on values of any type of any kind. However,
 you will be unable to define a function of that type, because the compiler will
 not know what register will hold the argument.) In contrast, writing
@@ -385,8 +385,8 @@ not know what register will hold the argument.) In contrast, writing
 val id : ('a : any) -> 'a
 ```
 
-does not do what you might think: it constrains a *usage site* of `'a`, stating
-that `'a` must have a subkind of `any` -- but of course `value` *is* a subkind
+constrains a *usage site* of `'a`, stating
+that `'a` must have a subkind of `any` -- but `value` *is* a subkind
 of `any`, so the default behavior of choosing `value` is unaffected. That is,
 the type `('a : any) -> 'a` is the same as just writing `'a -> 'a`.
 

jane/doc/extensions/_05-kinds/types.md

@@ -75,7 +75,7 @@ the component types>>` without constraining the kinds of any of the `ty_i`.
 
 * An applied type constructor `(ty_1, ..., ty_n) t` (where n >= 0) has the kind
 assigned to `t` at its declaration, with type arguments substituted into any
-type variables mentioned in `t`'s with-bounds. Each of the `ty_i` is constrained
+type variables mentioned in the `t` with-bounds. Each of the `ty_i` is constrained
 to be a subkind of the kind on the corresponding type parameter to `t`.
 
 * An object type `< f1 : ty_1; ...; fn : ty_n >` has kind `value mod

jane/doc/extensions/_06-uniqueness/reference.md

@@ -69,8 +69,8 @@ let bad r =
 The problem here is that the compiler can not determine whether `free r` might
 dereference `r.field1` again. As such, it would be unsafe to free `r.field1`.
 The uniqueness analysis carefully tracks which children of an allocation have
-already been consumed. This tracking also works with obvious aliases, such as
-simple renamings:
+already been consumed. This tracking also works with aliases, such as
+renamings:
 
 ```ocaml
 let okay r =

jane/doc/extensions/_07-comprehensions/01-intro.md

@@ -110,7 +110,7 @@ the conditions hold.  The order of the result is given by evaluating the clauses
 (`for ... and ...` and `when` alike) in order from left to right; they may be
 thought of as nested loops/conditionals.
 
-## A special-case optimization for simple (fixed-size) array comprehensions
+## A special-case optimization for fixed-size array comprehensions
 
 One somewhat unusual design choice is the decision to allow multiple iterators
 in a single clause, via `for ITERATOR_1 and ITERATOR_2 and ... and ITERATOR_N`,
@@ -137,7 +137,7 @@ right could depend on the values generated by those on the left.  Thus, the
 second example above (“Let’s describe some objects”) would preallocate an array
 of 6 strings and loop through it, whereas the fourth example (“Flatten a nested
 array”) would have to start with a smaller array and grow it as necessary.
-(Of course, this optimization does not apply to lists. The only thing we can do with a
+(This optimization does not apply to lists. The only thing we can do with a
 list is iterate over it, and the only way we can produce a list is by building it up piece
 by piece.)
 
@@ -151,5 +151,5 @@ per surrounding iteration before any of them begin to iterate.
 ## More details
 
 This should be enough to use comprehensions on a day-to-day basis; if you have
-more questions, or are simply curious about how things work on the inside, see
+more questions, or are curious about how things work on the inside, see
 the [details page](../details).

jane/doc/extensions/_07-comprehensions/02-details.md

@@ -107,7 +107,7 @@ iterated over (the `seq` of a `for pat in seq` iterator, or the `start` and
 `end` of a `for x = start to/downto end` iterator); the function argument is
 then to be called once for each item.  What goes in the function?  It will be
 the next iterator, desugared in the same way.  At any time, a `when` clause
-might intervene, which is simply desugared into a conditional that gates
+might intervene, which is desugared into a conditional that gates
 entering the next phase of the translation.
 
 Eventually, we reach the body, which is placed into the body of the innermost
@@ -176,9 +176,9 @@ size.
 The second source of extra complexity is the fixed-size array case.  In this
 case, we have to first compute the size of every iterator and multiply them
 together; for both of these operations, we have to check for overflow, in which
-case we simply fail.  We also check to see if any of the iterators would be
+case we fail.  We also check to see if any of the iterators would be
 empty (have size `0`), in which case we can shortcut this whole process and
-simply return an empty array.  Once we do that, though, the loop body is simpler
+return an empty array.  Once we do that, though, the loop body is lighter
 as there’s no need to double the array size, and we don’t need to cut the list
 down to size at the end.
 

jane/doc/extensions/_08-miscellaneous-extensions/polymorphic-parameters.md

@@ -53,7 +53,7 @@ all require defining a fresh type to contain `f`. These work-arounds
 require additional code at each call site to wrap `f` in the associated
 type.
 
-With polymorphic parameters, you can simply annotate `f` as
+With polymorphic parameters, you can annotate `f` as
 polymorphic:
 ```ocaml
 let create (f : 'a. 'a field -> 'a) =