correct nomenclature?

[macgyver]

Maybe I'm misunderstanding something but my comprehension of the docs was tripped up by the word "literal" in quotation marks. Feel free to close if you think it's too pedantic.

The array literal is a literal because it IS LITERALLY the array object (which is then assigned to a variable.) The list object is not a literal anything, because there is no syntax in native javascript to construct one except by calling the function.

[paldepind]

Hello @macgyver. Thank you for providing feedback on the documentation! :smile:

Let me try and explain what the docs are attempting to convey. In JavaScript if we want to create a concrete array with known elements then we can use a literal like [a, b, c]. Similarly, if we want to create a concrete list with known elements then we can use list(a, b, c). If we want to create an empty array we can write [] and if we want to create an empty list we can write list(). More generally, for any [{expr}] we can write list({expr}) and get a list with the same elements that the array would have had. Thus, whenever one would use the [...] notation to create an array one instead uses list(...) to create a list.

The array literal is a literal because it IS LITERALLY the array object (which is then assigned to a variable.) The list object is not a literal anything, because there is no syntax in native javascript to construct one except by calling the function.

I only agree partly with this. [0, 1] is an expression that evaluates to an array object. list(1, 2) is an expression that evaluates to a list object. They're basically the same thing. I think you're putting too much emphasis on the literal meaning of the word "literal". According to Wikipedia:

a literal is a notation for representing a fixed value in source code.

In this sense list(...) is not a literal because a literal involves syntax build into the language. That is why I put the word "literal" in quotes in the readme. But, besides the fact that one of them is special syntax and the other is not, there isn't much of a difference. In your PR you changed "literal" to "object". I don't think the word "object" says anything. [0, 1] is an array object and list(0, 1) is a list object. The docs could be changed to:

-// An array literal
+// An array object
 const myArray = [0, 1, 2, 3];
-// A list "literal"
+// A list object
 const myList = L.list(0, 1, 2, 3);

That would be equally correct but it wouldn't say anything interesting.

Based on you feedback I think it would be a good idea to use the word "literal" in a slightly more reserved way. The docs should explain the [...] <=> list(...) correspondence in a way that is as easy to understand as possible.

[macgyver]

Would these be correct statements?

• the list ~constructor~ function implements the interface of an array literal
• the input to the list ~constructor~ function is identical to the syntax for an array literal

[paldepind]

I think the term constructor function is typically used to describe functions that you have to use with new. As in new Foo(..).

[macgyver]

right on - updated

[paldepind]

Here is a proposal for a rewording. What do you think about it @macgyver? What can be improved?

As a replacement for array literals List offers the function list for constructing lists. Instead of using [...] to construct an array with the content ... one can use list(...) to construct a list with the same content.

// An array literal
const myArray = [0, 1, 2, 3];
// The List equivalent
const myList = L.list(0, 1, 2, 3);

[macgyver]

+1! very clear

[paldepind]

:smile:

Will you update the PR with that description?

[paldepind]

I'll do it :smile:

[macgyver]

Sorry for the tardy response, I was out of service for awhile. Thanks for merging!