Improve some wording in the functors tutorial

[neuroevolutus]

This PR adds some minor grammatical and wording changes to the functors tutorial that will hopefully make things clearer for new users of OCaml.

In particular, I made some changes to the aside about the with type constraint that may need particular review to ensure I did not state something that is semantically incorrect.

[cuihtlauac]

Thanks, @neuroevolutus, that note needs to be clarified. Your text is better than is initial one, do you think this improves on it:

Suggested change

**Note**: The functor `IterPrint.Make` exposes the type from the injected dependency (here first `List.t` then `Array.t`) as the type `t` required of the result module. That's why a `with type` constraint is needed. When customising a type that's not exposed by the result module (i.e. an _implementation detail_), the `with type` constraint is not needed. As a further consequence of this, we could even define a local type `t` within the `struct` block for use within the implementation, and such a type `t` would not shadow the type `t` of the result module.

**Note**: Modules received and returned by `IterPrint.Make` both have a type `t`. The `with type ... :=` constraint is needed to make the two `t` identical. This allows functions from the injected dependency and result module to use the 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 unnecessary.

Regarding your last sentence:

As a further consequence, we could even define a local type t within the struct block for use within the implementation, and such a type t would not shadow the type t of the result module.

This is a bit hard to grasp because it requires 1/ figuring out what the code would look like if modified with a local t and 2/ figuring out the shadowing concern.

However, I believe you have a valid point. This is a matter that needs to be addressed. Could we address it somewhere else in the document or do we need an additional example? We may even need a complete section to address naming and shadowing concerns in relationship with functor definitions.

What is our opinion on this?

[neuroevolutus]

Thanks so much for the rewording. I think it's a lot more succinct and even clearer now. I made sure to commit your suggestion.

This is a bit hard to grasp because it requires 1/ figuring out what the code would look like if modified with a local t and 2/ figuring out the shadowing concern.

I agree; that is a good point 😅. I think adding a new section with a concrete example to address these concerns would be really nice. I'll work on adding this section and make a new commit to get your feedback.

[neuroevolutus]

As a small aside, I added a small section on empty variants to the data types tutorial to give context for the use of a singular | as a placeholder type definition.

[cuihtlauac]

Thanks, @neuroevolutus, this is great! I wonder if the difference between = and := type constraint is needed. But overall, you are absolutely right, this matter is missing in the current version.

[cuihtlauac]

I understand your point. I must admit I had never fallen into that pitfall and wasn't aware of it.

What do you think about turning the narrative into something like:

t from with type takes over local t which only has a local scope?

Again, the idea is to make things more direct.

[neuroevolutus]

I agree; that sounds good. It sounds clearer to me as a reader.

[neuroevolutus]

I used "takes precedence over" in the rewording, but let me know if you feel it's clearer with just saying "takes over."

[christinerose]

Suggested change

**Note**: Modules received and returned by `IterPrint.Make` both have a type `t`. The `with type ... :=` constraint is needed to make the two `t` identical. This allows functions from the injected dependency and result module to use the 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 unnecessary.

**Note**: Modules received and returned by `IterPrint.Make` both have a type `t`. The `with type ... :=` constraint is needed to make the two `t` modules identical. This allows functions from the injected dependency and result module to use the 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 unnecessary.

It reads funny to me to have a plural (two) with just t -- is it accurate to have t modules instead? ...or t types?

Regardless, there needs to be a comma after i.e.

[neuroevolutus]

Thanks for catching that. I made sure to add the comma in that part.

With regards to the t, I think it may be fine to keep it as is since the t refers to two types rather than modules per se. What are your thoughts, @cuihtlauac?

[neuroevolutus]

I wonder if the difference between = and := type constraint is needed. But overall, you are absolutely right, this matter is missing in the current version.

Actually, this is something I was struggling with a bit. I realised when playing around with the code that with type ... = ... parses just fine but creates a compilation error. I read the section on modules in the OCaml manual, but it seemed to describe the with type ... = ... constraint and not the with type ... := ... one. Is there some intuition I'm missing on the difference between = and :=?

[Octachron]

This is not the intended use case for empty types (see https://ocaml.org/manual/emptyvariants.html for an explanation of why they were introduced). An abstract type works better as a placeholder for the use case you are describing. I would thus avoid mentioning empty variant types before the GADT introduction.

[neuroevolutus]

I see. That would make sense. I'll revert the corresponding commit.

[neuroevolutus]

I've edited the Binary functor example to make elt and t abstract types.

Thanks for the link to the manual! I'll check that out.

[Octachron]

To give a better example of what I meant by "abstract type are better placeholder", if you write

type empty = |
let f ([]: empty list) = ()

the function f is total: the only list of empty values is the empty list. But this is property is only true for empty types. In other words, by using empty types as placeholders one might accidentally capture properties that are only true for empty types.

[neuroevolutus]

I see. I think I better understand now. As an aside, are there any examples in the wild where using empty types and refutation cases for them come in handy when it comes to GADTs? I think I'm still fuzzy on the motivation for empty types.

[cuihtlauac]

I wonder if the difference between = and := type constraint is needed. But overall, you are absolutely right, this matter is missing in the current version.

Actually, this is something I was struggling with a bit. I realised when playing around with the code that with type ... = ... parses just fine but creates a compilation error. I read the section on modules in the OCaml manual, but it seemed to describe the with type ... = ... constraint and not the with type ... := ... one. Is there some intuition I'm missing on the difference between = and :=?

I believe we can move forward with this PR without exposing the difference between the
= and := constraints (see section 10.4 of the manual). We can add more material on that later

[cuihtlauac]

This looks good to me. Thnaks @neuroevolutus

[neuroevolutus]

This looks good to me. Thnaks @neuroevolutus

Thank you so much for all the feedback! I'm so happy to have had the chance to contribute.