Site Redo (cumbersome to use)

Hello @PirateJC , @PatrickRyan and com team,
First, I agree with the above. It didn’t strike me as such or as much, but I did notice this (and applied my personal ‘go-around’ method;)
I think this change for a better nav between BJS offerings will be a welcoming change (for the community, the devs and also for BJS#marketing).

I shall take this opportunity of passing over a ‘bunch’ of comments and feedback after the 4.2 update (which again, was an awesome update/upgrade)… It’s always easier to improve than to create or rethink, and some people who comment the doc today must not have seen or remember the old (r.i.p.) version;) Though, the old version doc wasn’t all that bad. I have used it and also found my way of using it. Same as I did for the new one.

I think what is important in the first place is to keep with the spirit/philosophy and build on the pillars. For me, the pillars of BJS are: 1) the Method/Product 2) the PG&snippets 3) the Inspector 4) the Community, (not in strict order but obviously the product/offering comes first) and then …one more (pillar) that has something to do with MoT and ‘consumer habit’, but I’m unable to clearly define it just right now (don’t know why…) Hopefully, yours are;)

Its a Typescript thing. Once upon a time a vector3 had three properties x, y and z, these were public. When you did

mesh.position = new BABYLON.Vector3(1, 2, 1);
mesh.position.z = 3;
console.log(mesh.position);

You would get { x:1, y:2, z:3 } and position was a property of mesh

Then, somewhere about v4.1, the properties of vector3 were changed to private and are _x, _y, _z. (Now there is a good reason for this but at a security level I do not have the knowledge to explain)

Since in Typescript you do not have direct access to private properties you have to build in an accessor to allow you access using setters and getters.

Now when you do

mesh.position = new BABYLON.Vector3(1, 2, 1);
mesh.position.z = 3;
console.log(mesh.position);

You get { _x:1, _y:2, _z:3 } (since JavaScript doesn’t really care about public and private) and now since position is allowed access to the private properties _x, _y, _z position is now an accessor not a property.

The API in the docs being created from the Typescript files the creator recognises whether a variable is public, in which case it adds it to the properties list, or is private with a setter or getter allowing access to it, in which case it adds it to the accessor list.

1 Like

The first example you explain is an “instance variable” or in other languages a “field”. A “property” means you are dealing with getters and setters aka mutators and accessors - functions that offer the same syntax as an instance variable, which control or are backed by a private instance variable. The reason for this is better control/encapsulation.

I’m not sure why typescript would only use the name of the “getter” to describe both the “getter and setter” , that did confuse me at first when I saw it.

I would say just change “accessors” to “properties” in the docs and all is good BUT then you already have a section incorrectly labeled “properties” which are actually “instance variables” or “fields”.

So both titles need to be updated for clarity

accessor and property are the names used in Typescript: https://www.typescriptlang.org/docs/handbook/classes.html

Keeping those names separate in the doc is a good thing I think because you know that a property is accessed without any intermediate code (you just read/write the value when you access it, there can be no side-effect), whereas if it’s an accessor you can have some in-between code running.

2 Likes

ahh the fragmentation of programming language semantics :wink:

since you use Typescript then you have reason of coarse - but in your link even they refer to “properties” as “fields” and “instance members” in the fine print. Yet, do not call accessors , properties , which other programming languages will disagree about.

all good then