Standard text for accessor/read only properties

[hamishwillee]

Properties can be read-only or may be both read and written. The different areas of the docs seem to have standard ways of identifying them, but they are different.

• Web APIs identify the read-only properties by having the summary text like": "The bar read-only property of the foo interface. Read/write properties are assumed (so they just omit "read-only").
• JavaScript uses the term "accessor" in exactly the same way that apis use "read-only".

Web APIs also use the {{readonly_inline}} macro in the parent interface to show that the item is read-only. I'm not sure whether javascript does the same thing or not, but it certainly omits it for this case: TypedArray.length.

What pattern should we use for Web Assembly.

I think we should adopt the same pattern everywhere - silly to have different words for exactly the same thing. My preference is to use the WebAPI approach - I think "read-only" is more accessible to more people than accessor, and also matches up with the macro.

I'd probably be even happier with a metadata bases approach for indicating this, in the same way as we are heading towards for static methods, properties etc. Why? Because then we can in theory match up to the IDL to automate we are getting things right and check changes.

[Josh-Cena]

There are two types of read-only properties:

const obj = {};
Object.defineProperty(obj, "readonly1", {
  value: 1,
  configurable: false,
  writable: false,
});

Object.defineProperty(obj, "readonly2", {
  get() {
    return 2;
  },
  set: undefined,
  configurable: false,
});

Both would silently fail in sloppy mode and throw in strict mode. The first one is an actual "read-only" property since it's a data property. The second one is a "getter-only" property. They are already represented differently in our docs:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/length

  The length property is an accessor property whose set accessor function is undefined, meaning that you can only read this property.

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined
  • Uses a property attribute table

[hamishwillee]

Thanks @Josh-Cena , If that's the way things are done and it is a useful distinction then great!

@fiji-flo @wbamberg, if this is the approach, do you think you guys might care to create docs on "the rules" for Javascript?:
https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types

[ghost]

Josh-Cena's reply does indeed elucidate the JavaScript differences, but there's also the issue of the Web API difference: Web APIs never* use JavaScript properties on object instances, rather using getters/setters. They're called "read-only properties" nonetheless. Should this be considered to be incorrectly documented?

* I have only heard of one case of this occuring with any web binding: TextEncoder#encodeInto returns a dictionary. Nonetheless, very uncommon.

[Josh-Cena]

I think for Web API no one really cares. I haven't encountered a need to hack around the difference between data and accessor properties—it's all third-grade JS when it comes to web. I think it's fine to keep those as "readonly", but I want to get the JS semantics right.

[Josh-Cena]

Speaking of the practical difference between a readonly data property and a getter-only accessor property. It's really minor, but it affects how subclassing works (and is the entire reason why the RegExp flag properties are moved from data to accessor properties).

class RegExp {
  get flags() {
    // Pretend it actually reads the internal data structure
    return "dgi";
  }
}

class BetterRegExp extends RegExp {
  get flags() {
    console.log("Getting flags");
    return super.flags;
  }
}

console.log(new BetterRegExp().flags);

// Getting flags
// dgi

On the other hand, because all data properties are defined on RegExp instances instead of on its prototype, you can't make these "enhancement properties" that easily. If the RegExp constructor defines flags on the instance, then the derived class's accessor would not be consulted at all.

class RegExp {
  constructor() {
    Object.defineProperty(this, "flags", { value: "dgi" });
  }
}

class BetterRegExp extends RegExp {
  get flags() {
    console.log("Getting flags");
    return super.flags;
  }
}

console.log(new BetterRegExp().flags);
// dgi

[ghost]

Regarding,

What pattern should we use for Web Assembly.

As WebAssembly is a W3C spec., not ECMA, I would suggest that it wholly take after Web APIs.
(Also see #151)

As examples:

• If the final decision is that there will be a split between Web APIs vs. ECMAScript built-ins, then WebAssembly should follow the Web APIs.
• If the decision is that they should be joined or otherwise clarify between accessors/data properties in Web APIs, then WebAssembly should use accessor vs. data property, as appropriate.

[hamishwillee]

@Josh-Cena @phosra I think we're in agreement:

• Web Assembly uses read-only
• Web APIs continue to use read-only
• JavaScript continue to use accessor and patterns that differentiate the underlying property/getter.

This comes down to audience. The distinction of property types is not useful or generally even meaningful for Web APIs or Web Assembly. However this distinction is meaningful for some non-trivial fraction of the Javascript documentation readership and does no real harm to the broader audience.

OK?

@Josh-Cena That all said, IMO:

1. this implies we need javascript page type documentation separate from the Web API reference contributor docs covering JavaScript ways of doing things. This doesn't have to be particularly detailed - the Web API docs leverage pointing to good reference examples to copy.
2. You might want to consider requesting a macro equivalent to {{readonly_inline}} like {{accessor_inline}} for the top level doc. It's a good pattern to easily be able to see at that level what type of property something is.
3. The discussion of titles for getters whatever is separate and worth having separately. If the distinction is useful then working out whether it should be in the title or somewhere else (e.g. page-type metadata) is important.

[ghost]

One final suggestion from myself - if it doesn't exist - would be that a low-level/advanced page explaining how Web APIs are exposed to JavaScript, for example that most properties are accessors, and that read-only maps to getter-only?!
It imagine that it would be useful for the same audience that cares about this distinction, among other details.