Improve Arcade polyline paths array documentation

[Bud]

Regarding the Arcade developer documentation:

I find the description of the Polyline paths array to be confusing:

"A three-dimensional array of numbers. The inner-most array contains the x,y,z,m coordinates of a single point. The second dimension contains additional points making up a line segment. The third dimension allows the polyline to have multiple segments."

Could that blurb be re-worded so that it's more intuitive?

Something like this?
- An outer array to hold the multi-parts:         [multiple parts here]
- A middle array of one or more multi-parts: [multiple parts: [p0], [p1]  ]
- An inner array that is the sets of vertices:     [multiple parts: [p0:  [X,Y], [X,Y], [X,Y] ], [p:1  [X,Y], [X,Y]  ] ]

I think a more intuitive explanation would be helpful. I've heard from a few different people that said they also found the existing wording confusing.


Related info here: https://community.esri.com/t5/arcgis-pro-questions/arcade-what-does-quot-zero-dimensional-geometry/m...

[JohannesLindner]

I think the explanation is quite intuitive and tells you everything you need to know in a very concise way.

A three-dimensional array of numbers

We're storing numeric information. The numbers are stored in a hirarchical structure. We have to go 3 levels deep to get the numbers

The inner-most array contains the x,y,z,m coordinates of a single point

So that's what the numbers represent, cool. It makes sense to put that information first, instead of going though the structure top-down. This translates to p = [x, y, z, m]

The second dimension contains additional points making up a line segment

We already know the second dimension contains multiple instances of the first dimension (that'
s what "dimension" means in the context of arrays: Higher dimensions hold multiple instances of lower dimensions). The new information is that these form a segment. This means segment = [p0, p1, p2]

The third dimension allows the polyline to have multiple segments

Alright, that's why we need the third dimension. This means paths = [segment0, segment1]

So, from just 4 sentences, I know what the data represents, how it is structured, and how I can get to the information I need. The documentation is intuitive enough.

The real problem is that it is somewhat wrong:

It is correct for creating a Polyline (or Polygon). But if you want to read the paths/rings property of an existing geometry, it is not number[][][] (3D number array), but Point[][] (2D Point array).

var p0 = [1, 1, 0, 0]  // [x, y, z, m]
var p1 = [2, 2, 0, sqrt(2)]
var segment0 = [p0, p1]
var paths = [segment0]
Console("paths used to create the geometry:")
Console(paths + "\n")

var geo = Polyline({"paths": paths, "spatialReference": {"wkid": 25832}})
Console("paths read from the geometry:")
Console(geo.paths + "\n")

// I want to get the x coordinate of the start point.
//Console(geo.paths[0][0][0])  // this will fail, because geo.paths is not number[][][], but Point[][]
Console(geo.paths[0][0].x)
Console(geo.paths[0][0].type)

paths used to create the geometry:
[[[1,1,0,0],[2,2,0,1.414213562373095]]]

paths read from the geometry:
[[{"x":1,"y":1,"z":0,"m":0,"spatialReference":{"wkid":25832}},{"x":2,"y":2,"z":0,"m":1.414213562373095,"spatialReference":{"wkid":25832}}]]

1
Point