[Docs] Intended meaning of "instantiate" is unclear in places

[nmsmith]

Where is the problem?

https://docs.modular.com/mojo/manual/parameters/index.html#using-parameterized-types-and-functions

What can we do better?

Early in the Mojo docs, the term "instantiate" is used in the traditional OOP sense: to "instantiate" is to create an instance of a data type.

But the page on parameters uses the term in an unclear manner. Consider the following sentence:

You can instantiate parametric types and functions by passing values to the parameters in square brackets.

It is unclear to me which of the following two meanings the author intends to convey:

1. Providing parameter values to a parametric type/function "instantiates" it into a non-parametric type/function.
2. In order to invoke the constructor of a parametric type (i.e. to create an "instance" of that type), you must first provide parameter values.

A later use of "instantiate" on the same page suggests that the former meaning was intended:

The cast() method is a generic method definition that gets instantiated at compile-time instead of runtime.

If so, then the term "instantiate" is being used for two distinct concepts in the documentation, and either this should be clarified, or perhaps terminology should be adjusted to avoid overloading the term.

Anything else?

No response

[soraros]

They are the same if you take the first reading (which is quite established at least in FP literature) as "create an instance of some concrete function type".

[nmsmith]

I think what you mean is that some FP languages have a notion of "type constructor". Applying the terminology to Mojo, SIMD would be a type constructor, and SIMD[DType.float32, 4] would be the application of the type constructor to the parameter values DType.float32 and 4, which creates an "instance" of that type constructor (i.e. a type), thereby justifying the term "instantiation".

I would be happy to see this kind of terminology used in Mojo, but for this to work, we'd probably need to tweak the terminology we're using so that people don't get confused between:

• types and type constructors
• instances of types (i.e. objects) and instances of type constructors (i.e. types)
• functions and function constructors

Maybe we could coin the terms "paratype" and "parafunction". Instantiating a paratype gives you a type, and instantiating a parafunction gives you a function.

[soraros]

I think what you mean is that some FP languages have a notion of "type constructor".

Related, but not really. I meant usage like in this wikipedia entry.

My point is really, your two concepts both have long history in CS (or, OOP people don't own the word "instantiate"), and they are somewhat compatible. The core idea is similar: instantiation involves taking something abstract (like a class, a generic type, or a template) and creating something concrete from it (like an object, a specific type, or a specific implementation).

BTW, type constructors don't have "instances"/terms (because they are not of type Type), only constructed types do.

[arthurevans]

This is a good point. Perhaps we should probably introduce another term here because this is a little fuzzy.

To use a parametric type or function, you need to bind the parameters to create a concrete type (which can be instantiated) or a concrete function (which can be called). In many cases you bind the parameters and instantiate the type (or call the function) at the same time. And sometimes the parameter values are inferred, so it's not clear that the parameters are being bound at all.

[mikowals]

I think the use of "instantiation" in the rebind section of sharp edges refers to a related concept but in terms of the compile process. So those uses of instantiation might need to be considered along with instantiate .

These are the quotes from there:

• "One of the consequences of Mojo not performing function instantiation in the parser like C++ is ..."
• "This is because the parser fully type-checks the function without instantiation, ..."