Review edits

Author: Cuihtlauac ALVARADO

data/tutorials/language/1ms_00_modules.md

@@ -21,29 +21,27 @@ Modules are collections of definitions grouped together. This is the basic means
 ### File-Based Modules
 
 In OCaml, every piece of code is wrapped into a module. Optionally, a module
-itself can be a submodule of another module, pretty much like directories in a
-file system.
+itself can be a [submodule](#submodules) of another module, pretty much like
+directories in a file system.
 
-When you write a program using two files named `athens.ml` and `berlin.ml`,
-each automatically defines a module named `Athens` and `Berlin`, which provides
-whatever you put into the files.
+Here is a program using two files: `athens.ml` and `berlin.ml`. Each file
+defines a module named `Athens` and `Berlin`, respectively.
 
-Here is the code in the file `athens.ml`:
+Here is the file `athens.ml`:
 <!-- $MDX file=examples/athens.ml -->
 ```ocaml
 let hello () = print_endline "Hello from Athens"
 ```
 
-This is what is in `berlin.ml`:
+Here is the file `berlin.ml`:
 <!-- $MDX file=examples/berlin.ml -->
 ```ocaml
 let () = Athens.hello ()
 ```
 
 To compile them using [Dune](https://dune.build/), at least two
 configuration files are required:
-* The `dune-project` file contains project-wide configuration data.
-  Here's a very minimal one:
+* The `dune-project` file contains project-wide configuration.
   ```lisp
    (lang dune 3.7)
   ```
@@ -54,27 +52,24 @@ configuration files are required:
   (executable (name berlin))
   ```
 
-Here is a possible way to create those files, build the source, and run the
-executable:
+After you create those files, build and run them:
 <!-- $MDX dir=examples -->
 ```bash
-$ echo "(lang dune 3.7)" > dune-project
-
-$ echo "(executable (name berlin))" > dune
-
 $ dune build
 
 $ dune exec ./berlin.exe
-Hello
+Hello from Athens
 ```
 
-Actually, `dune build` is optional. Running `dune exec` would have triggered the
-compilation. Note that in the `dune exec` command, the parameter `./berlin.exe`
-is not a file path. This command means “execute the content of the file
-`./berlin.ml`.” However, the executable file is stored and named differently.
+Actually, `dune build` is optional. Running `dune exec ./berlin.exe` would have
+triggered the compilation. Note that in the `dune exec` command, the parameter
+`./berlin.exe` is not a file path. This command means “execute the content of
+the file `./berlin.ml`.” However, the executable file is stored and named
+differently.
 
 In a project, it is preferable to create the `dune` configuration files and
-directory structure using the `dune init project` command.
+directory structure using the `dune init project` command. Refer to the Dune
+documentation for more on this matter.
 
 ### Naming and Scoping
 
@@ -84,38 +79,40 @@ always starts with a capital letter: `Athens`) followed by a dot and the
 thing you want to use (`hello`). It may be a value, a type constructor, or
 anything the module provides.
 
-If you are using a module heavily, you can directly access its contents. To do
-this, use the `open` directive. In our example, `berlin.ml` could have been
+If you are using a module heavily, you might want to `open` it. This brings the
+module's definitions into scope. In our example, `berlin.ml` could have been
 written:
 <!-- $MDX skip -->
 ```ocaml
 open Athens
 let () = hello ()
 ```
 
-Using `open` is optional. Usually, we don't open the module `List` because it
-provides names other modules also provide, such as `Array` or `Option`. Other
-modules like `Printf` provide names that aren't subject to conflicts, such as
-`printf`. Placing `open Printf` at the beginning of the file avoids writing
-`Printf.printf` all over the place.
+Using `open` is optional. Usually, we don't open a module like `List` because it
+provides names other modules also provide, such as `Array` or `Option`. Modules
+like `Printf` provide names that aren't subject to conflicts, such as `printf`.
+Placing `open Printf` at the top of a file avoids writing `Printf.printf` repeatedly.
 ```ocaml
 open Printf
 let data = ["a"; "beautiful"; "day"]
 let () = List.iter (printf "%s\n") data
 ```
 
- The standard library is a module called `Stdlib` where modules `List`,
- `Option`, `Either`, and others are [submodules](#submodules). Implicitly, all
- OCaml begins with `open Stdlib`. That avoids writing `Stdlib.List.map`,
- `Stdlib.Array`, or using `Stdlib.` anywhere.
+ The standard library is a module called `Stdlib`. It contains
+ [submodules](#submodules) `List`, `Option`, `Either`, and more. By default, the
+ OCaml compiler opens the standard library, as if you had written `open Stdlib`
+ at the top of every file. Refer to Dune documentation if you need to opt-out.
 
-There are also two means to open modules locally:
+You can open a module inside a definition, using the `let open ... in` construct:
 ```ocaml
 # let list_sum_sq m =
     let open List in
     init m Fun.id |> map (fun i -> i * i) |> fold_left ( + ) 0;;
 val list_sum_sq : int -> int = <fun>
+```
 
+The module access notation can be applied to an entire expression:
+```ocaml
 # let array_sum_sq m =
     Array.(init m Fun.id |> map (fun i -> i * i) |> fold_left ( + ) 0);;
 val array_sum_sq : int -> int = <fun>
@@ -125,19 +122,17 @@ val array_sum_sq : int -> int = <fun>
 
 By default, anything defined in a module is accessible from other modules.
 Values, functions, types, or submodules, everything is public. This can be
-restricted. That allows distinguishing content provided to other modules from
-internal use content. What is internal is kept private and not available from
-other modules.
+restricted to avoid exposing definitions that are not relevant from the outside.
 
 For this, we must distinguish:
-- Implementation, which is a module's actual content.
-- Interface, which is a module's public content list.
+- The definitions inside a module (the module implementation)
+- The public declarations of a module (the module interface)
 
-An `.ml` file contains a module implementation. By default, without an explicitly
-defined interface, an implementation has a default interface where everything is
-public.
+An `.ml` file contains a module implementation; an `.mli` file contains a module
+interface. By default, when no corresponding `.mli` file is provided, an
+implementation has a default interface where everything is public.
 
-Copy the `athens.ml` file into `cairo.ml` and change it with this contents:
+Copy the `athens.ml` file into `cairo.ml` and change its contents:
 <!-- $MDX file=examples/cairo.ml -->
 ```ocaml
 let message = "Hello from Cairo"
@@ -177,13 +172,13 @@ let () = Cairo.hello ()
 
 Update the `dune` file to allow the compilation of this example aside from the
 previous one.
-
 <!-- $MDX dir=examples -->
-```bash
-$ echo "(executables (names berlin delhi))" > dune
-
-$ dune build
+```lisp
+(executables (names berlin delhi))
+```
 
+Compile and execute both programs:
+```shell
 $ dune exec ./berlin.exe
 Hello from Athens
 
@@ -228,7 +223,6 @@ type aleph = Ada | Alan | Alonzo
 type bet = bool
 
 type gimel = Christos | Christine
-
 let gimel_of_bool b = if (b : bet) then Christos else Christine
 let gimel_flip = function Christos -> Christine | Christine -> Christos
 let gimel_to_string x = "Christ" ^ match x with Christos -> "os" | _ -> "ine"
@@ -240,7 +234,6 @@ let dalet_of = function
   | Some (Either.Right x) -> Donald x
 ```
 
-
 Update file `dune`:
 ```lisp
 (executables (names berlin delhi) (modules berlin delhi))
@@ -250,6 +243,9 @@ Update file `dune`:
 Run the `dune utop` command, it triggers `Exeter`'s compilation, launches `utop` and loads `Exeter`.
 ```ocaml
 # open Exeter;;
+
+# #show aleph;;
+type aleph = Ada | Alan | Alonzo
 ```
 
 Type `aleph` is public. Values can be created or accessed.
@@ -276,25 +272,25 @@ val gimel_of_bool : bool -> gimel
 - : string = "Christine"
 ```
 
-Type `gimel` is _abstract_. Values are available, but only as function result or argument. Only the provided functions `gimel_of_bool`, `gimel_flip`, and ` gimel_to_string` and polymorphic functions can receive or return `gimel` values.
+Type `gimel` is _abstract_. Values can be created or manipulated, but only as function results or arguments. Only the provided functions `gimel_of_bool`, `gimel_flip`, and `gimel_to_string` or polymorphic functions can receive or return `gimel` values.
 ```ocaml
 # #show dalet;;
 type dalet = private Dennis of int | Donald of string | Dorothy
 
-# Dennis 42;;
+# Donald 42;;
 Error: Cannot create values of the private type Exeter.dalet
 
 # dalet_of (Some (Either.Left 10));;
 - : dalet = Dennis 10
 
 # let dalet_to_string = function
-  | None -> "Dorothy"
-  | Some (Either.Left _) -> "Dennis"
-  | Some (Either.Right _) -> "Donald";;
-val dalet_to_string : ('a, 'b) Either.t option -> string = <fun>
+  | Dorothy -> "Dorothy"
+  | Dennis _ -> "Dennis"
+  | Donald _ -> "Donald";;
+val dalet_to_string : dalet -> string = <fun>
 ```
 
- The type `dalet` is _read-only_. Pattern matching is possible, but values can only be constructed by the provided functions, here `dalet_of`.
+The type `dalet` is _read-only_. Pattern matching is possible, but values can only be constructed by the provided functions, here `dalet_of`.
 
 Abstract and read-only types can be either variants, as shown in this section, records, or aliases. It is possible to access a read-only record field's value, but creating such a record requires using a provided function.
 
@@ -322,11 +318,13 @@ let () =
   Florence.print_goodbye ()
 ```
 
-The module `Hello` is a submodule of module `Florence`.
+Definitions from a submodule are access by chaining module names, here
+`Florence.Hello.print`.
 
-### Submodule Interface
+### Submodule with Signatures
 
-We can also restrict the interface of a submodule. Here is a second version of the `florence.ml` file:
+To define an interface to a submodule we can provide a _module signature_. This
+is done in this second version of the `florence.ml` file:
 ```ocaml
 module Hello : sig
  val print : unit -> unit
@@ -340,9 +338,9 @@ let print_goodbye () = print_endline "Goodbye"
 
 The first version made `Florence.Hello.message` public. In this version it can't be accessed from `glasgow.ml`.
 
-### Interfaces are Types
+### Module Signatures are Types
 
-The role played by interfaces to implementations is akin to the role played by types to values. Here is third possible way to write file `florence.ml`:
+The role played by module signatures to implementations is akin to the role played by types to values. Here is a third possible way to write file `florence.ml`:
 ```ocaml
 module type HelloType = sig
   val hello : unit -> unit
@@ -356,9 +354,9 @@ end
 let print_goodbye () = print_endline "Goodbye"
 ```
 
-The interface used previously for `Florence.Hello` is turned into a `module type` called `HelloType`. Later, when defining `Florence.Hello`, it is annotated with `HelloType` as a value could be. The `HelloType` acts as a type alias.
+First, we define a `module type` called `HelloType` which defines the same module interface as previously. Instead of providing the signature when defining the `Hello` module, we use the `HelloType` module type.
 
-This allows writing once interfaces shared by several modules. An implementation satisfies any module type listing some of its contents. This implies a module may have several types and there are subtyping relationship between module types.
+This allows writing interfaces shared by several modules. An implementation satisfies any module type listing some of its contents. This implies a module may have several types and there is a subtyping relationship between module types.
 
 ## Module Manipulation
 
@@ -378,9 +376,7 @@ module Unit :
   end
 ```
 
-There is online documentation for each library, for instance, [`Unit`](/api/Unit.html).
-
-The OCaml compiler tool chain can be used to dump a `.ml` file default interface.
+The OCaml compiler tool chain can be used to dump an `.ml` file's default interface.
 ```shell
 $ ocamlc -c -i cairo.ml
 val message : string
@@ -389,7 +385,7 @@ val hello : unit -> unit
 
 ### Module Inclusion
 
-Let's say we feel that a function is missing from the standard `List` module,
+Let's say we feel that a function is missing from the `List` module,
 but we really want it as if it were part of it. In an `extlib.ml` file, we
 can achieve this effect by using the `include` directive:
 
@@ -402,12 +398,13 @@ module List = struct
 end
 ```
 
-It creates a module `Extlib.List` that has everything the standard `List`
-module has, plus a new `uncons` function. In order to override the default `List` module from another `.ml` file, we merely need to add `open Extlib` at the beginning.
+It creates a module `Extlib.List` that has everything the standard `List` module
+has, plus a new `uncons` function. In order to override the default `List`
+module from another `.ml` file, we need to add `open Extlib` at the beginning.
 
 ## Stateful Modules
 
-A module may have an internal state. This is the case standard library `Random` module. The functions `Random.get_state` and `Random.set_state` provide read and write access to the internal state, which is nameless and has an abstract type.
+A module may have an internal state. This is the case for the `Random` module from the standard library. The functions `Random.get_state` and `Random.set_state` provide read and write access to the internal state, which is nameless and has an abstract type.
 ```ocaml
 # let s = Random.get_state ();;
 val s : Random.State.t = <abstr>
@@ -425,7 +422,9 @@ val s : Random.State.t = <abstr>
 - : int = 89809344
 ```
 
-Values returned by `Random.bits` will differ in your setup, but the first and third calls return the same results, showing that the internal state was reset.
+Values returned by `Random.bits` will differ when you run this code. The first
+and third calls return the same results, showing that the internal state was
+reset.
 
 ## Conclusion