Improve some wording in the functors tutorial (#2023)

* Reorder a paragraph in functors tutorial to improve content flow

* Grammar: add the word "by" in functors tutorial

* Clarify note on `with type` constraint in functors tutorial

* Simplify note on `with type` constraint in functors tutorial

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

* Grammar: add the word "of" in functors tutorial

* Add section on empty variants in basic data types tutorial

* Add missing definition to `Binary` functor in functors tutorial

* Grammar: use "facilitate" over "allows" in functors tutorial

* Add section on naming and scoping to functors tutorial

* Reword section header in functors tutorial

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

* Use more self-explanatory constructor in functors tutorial

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

* Improve compiler error explanation in functors tutorial

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

* Remove unnecessary word in functors tutorial

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

* Remove small digression from functors tutorial

* Simplify sentence in functors tutorial

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

* Reword explanation on scoping in functors tutorial

* Remove extra space and add comma after "i.e." in functors tutorial

* Revert "Add section on empty variants in basic data types tutorial"

This reverts commit 03758f0.

* Remove empty variants as placeholders in `Binary` functor example

* Apply suggestions from code review

* Apply suggestions from code review

* Update data/tutorials/language/1ms_01_functors.md

* Clarify note on `with type` constraint in functors tutorial

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

* Typo: change "In" to "If" in functors tutorial

* Apply suggestions from code review

* Update data/tutorials/language/1ms_01_functors.md

---------

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

Author: neuroevolutus

data/tutorials/language/1ms_01_functors.md

@@ -62,7 +62,7 @@ Here is how this reads (starting from the bottom, then going up):
 
 **Note**: Most set operations need to compare elements to check if they are the same. To allow using a user-defined comparison algorithm, the `Set.Make` functor takes a module the specifies both the element type `t` and the `compare` function. Passing the comparison function as a higher-order parameter, as done in `Array.sort`, for example, would add a lot of boilerplate code. Providing set operations as a functor allows specifying the comparison function only once.
 
-Here is an example how to use `Set.Make`:
+Here is an example of how to use `Set.Make`:
 
 **`funkt.ml`**
 
@@ -79,10 +79,6 @@ This defines a module `Funkt.StringSet`. What `Set.Make` needs are:
 - Type `t`, here `string`
 - Function allowing to compare two values of type `t`, here `String.compare`
 
-However, since the module `String` defines
-- Type name `t`, which is an alias for `string`
-- Function `compare` of type `t -> t -> bool` compares two strings
-
 This can be simplified using an _anonymous module_ expression:
 ```ocaml
 module StringSet = Set.Make(struct
@@ -93,6 +89,10 @@ end)
 
 The module expression `struct ... end` is inlined in the `Set.Make` call.
 
+However, since the module `String` already defines
+- Type name `t`, which is an alias for `string`
+- Function `compare` of type `t -> t -> bool` compares two strings
+
 This can be simplified even further into this:
 ```ocaml
 module StringSet = Set.Make(String)
@@ -156,14 +156,14 @@ let _ =
 
 This allows the user to seemingly extend the module `String` with a submodule `Set`. Check the behaviour using `opam exec -- dune exec funkt < dune`.
 
-## Functors Allows Parametrising Modules
+## Parametrising Modules with Functors
 
 ### Functors From the Standard Library
 
 A functor is almost a module, except it needs to be applied to a module. This turns it into a module. In that sense, a functor allows module parametrisation.
 
 That's the case for the sets, maps, and hash tables provided by the standard library. It works like a contract between the functor and the developer.
-* If you provide a module that implements what is expected, as described the parameter interface
+* If you provide a module that implements what is expected, as described by the parameter interface
 * The functor returns a module that implements what is promised, as described by the result interface
 
 Here is the module's signature that the functors `Set.Make` and `Map.Make` expect:
@@ -241,9 +241,10 @@ module type S = sig
 end
 
 module Binary(Elt: OrderedType) : S = struct
-  type elt = | (* Replace by your own *)
-  type t = | (* Replace by your own *)
+  type elt (* Add your own type definition *)
+  type t (* Add your own type definition *)
   (* Add private functions here *)
+  let empty = failwith "Not yet implemented"
   let is_empty h = failwith "Not yet implemented"
   let insert h e = failwith "Not yet implemented"
   let merge h1 h2 = failwith "Not yet implemented"
@@ -370,7 +371,50 @@ let _ =
 
 Check the program's behaviour using `opam exec -- dune exec funkt < dune`.
 
-**Note**: The functor `IterPrint.Make` returns a module that exposes the type from the injected dependency (here first `List.t` then `Array.t`). That's why a `with type` constraint is needed. When parametrising other something not exposed by the module (and _implementation detail_), the `with type` constraint is not needed.
+**Note**: Modules received and returned by `IterPrint.Make` both have a type `t`. The `with type ... := ...` constraint exposes that the two types `t` are the same. This makes functions from the injected dependency and result module use the exact same type. When the parameter's contained type is not exposed by the result module (i.e., when it is an _implementation detail_), the `with type` constraint is not necessary.
+
+### Naming and Scoping
+
+The `with type` constraint unifies types within a functor's parameter and result modules. We've used that in the previous section. This section addresses the naming and scoping mechanics of this constraint.
+
+Naively, we might have defined `Iter.Make` as follows:
+
+```ocaml
+module Make(Dep: Iterable) : S = struct
+  type 'a t = 'a Dep.t
+  let f = Dep.iter (fun s -> Out_channel.output_string stdout (s ^ "\n"))
+end
+```
+
+If the function `f` isn't used, the project compiles without error.
+
+However, since `Make` is invoked to create module `IterPrint` in `funkt.ml`, the project fails to compile with the following error message:
+
+```shell
+5 | ..stdin
+6 |   |> In_channel.input_lines
+7 |   |> List.concat_map Str.(split (regexp "[ \t.,;:()]+"))
+8 |   |> StringSet.of_list
+9 |   |> StringSet.elements
+Error: This expression has type string list
+       but an expression was expected of type string IterPrint.t
+```
+
+Outside the functor, it is not known that `type 'a t` is set to `Dep.t`. In `funkt.ml`, `IterPrint.t` appears as an abstract type exposed by the result of `Make`. This is why the `with type` constraint is needed. It propagates the knowledge that `IterPrint.t` is the same type as `Dep.t` (`List.t` in this case).
+
+The type constrained using `with type` isn't shadowed by definitions within the functor body. In the example, the `Make` functor can be redefined as follows:
+
+```ocaml
+module Make(Dep: Iterable) : S with type 'a t := 'a Dep.t = struct
+  type 'a t = LocalType
+  let g LocalType = "LocalType"
+  let f = Dep.iter(fun s ->
+    Out_channel.output_string stdout (g LocalType ^ "\n");
+    Out_channel.output_string stdout (s ^ "\n"))
+end
+```
+
+In the example above, `t` from `with type` takes precedence over the local `t`, which only has a local scope. Don't shadow names too often because it makes the code harder to understand.
 
 ## Write a Functor to Extend Modules