API structure conventions: syntax sections for properties?

[Elchi3]

This came up in mdn/content#4401 (comment)

@hamishwillee and I are wondering what to with property pages with regards to syntax sections.

It is a bit weird that many property reference pages have a syntax section that try to demonstrate syntax. Unlike methods or constructors, there isn't really a signature or the like to show.

There have been a few strategies that came up and we should standardize a convention (or, there probably is a convention but I'm questioning it).

Option 0

No syntax for properties. There is no syntax section at all.

Option 1

Show how to use a property as a code example (on these pages there are often duplicates in syntax and example sections)
https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/fftSize#syntax

var audioCtx = new AudioContext();
var myListener = audioCtx.listener;
myListener.forwardX.value = 0;

or sometimes

var curValue = analyserNode.fftSize;
analyserNode.fftSize = newValue;

Option 2

Explicitly call out getter and setter to be more of a syntax section and less like a code example
https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/origin#syntax
https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hash

Read only:

// Getter
string = anchor.origin;

// No setter; read-only property

Read write:

// Getter
string = anchor.hash;
// Setter
anchor.hash = string;

---

I'm voting for option 2. But I'm open to hear if that's the best way to show how properties' getter and setter behave.

[chrisdavidmills]

I prefer option 2 as well. It is short and to the point, it clearly demonstrates the read-only status and what the different forms look like (more friendly to beginners that just saying "it's read-only" or whatever and expecting them to know what that entails), and it is in less danger of duplicating parts found in Examples sections. Works for me.

[rachelandrew]

I'd also opt for option 2, I've written a load of these recently and agree they often end up similar to the examples, or just not very useful.

cc: @jpmedley who may have input on this.

[wbamberg]

FWIW I think option 0 is best. It looks like option 2 really conveys only one bit of information, which is whether the property is read-only.

If so this is a lot of words to say that and it is harder to read, I think, that just "This property is read-only." (which we already say in the page, so it's duplicated in option 2). What would be awesome would be to represent "read-only" as a front matter property of property pages, and render it consistently in the docs.

FWIW in stumptown we didn't include "syntax" for property pages: https://github.com/mdn/stumptown-content/blob/master/recipes/javascript-property.yaml

[hamishwillee]

What would be awesome would be to represent "read-only" as a front matter property of property pages, and render it consistently in the docs.

I am also interested in the type of the object. I like the idea of this stuff being in metadata because then you can more easily run checkers to confirm the needed information is present, and later on decide how to render.

Upshot - I lean towards option 0 for syntax, but we need some way to capture this.

[Elchi3]

It looks like option 2 really conveys only one bit of information, which is whether the property is read-only.

This is very true and maybe there are better ways to represent this clearly. Happy to conclude this with option 0.

[jpmedley]

I like option 2, but I'm not fond of using the terms 'getter' and 'setter'. Those are IDL specific terms. Anyone new to web programming, whether they're an experienced coder or not, is more likely to know the terms 'read' and 'write'. Option 2 also allows for conveying what the data type takes or returns (string, number, etc.). I've always tried to give the setting or returning value a name that conveys what it is. Joe Medley | Technical Writer, Chrome DevRel | ***@***.*** | 816-678-7195 *If an API's not documented it doesn't exist.*

…

On Tue, Apr 27, 2021 at 7:09 AM Florian Scholz ***@***.***> wrote: It looks like option 2 really conveys only one bit of information, which is whether the property is read-only. This is very true and maybe there are better ways to represent this clearly. Happy to conclude this with option 0. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <mdn/content#4476 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB6S7C55JGEV7ETHPBQIUQLTK3ARTANCNFSM43SKXBHA> .

[meyerweb]

Having recently done a bunch of these while working on the Temporal API, I lean toward option 0, especially since just about property in Temporal is read-only. I could live with Option 2.

[Elchi3]

Another thing I forgot but that supports option 0: In the JS docs, we actually have a table made especially for properties only.
See e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/E where it presents if the property is writable, enumerable, configurable.
That said, there are alternative ways to represent read-onliness and the like and a syntax section like in option 2 is probably not the best way to communicate this kind of information.

If there is no further input here, I'd like to close and decide for option 0.

[hamishwillee]

I agree. (though I think a separate issue might be opened to agree properties documentation like in Math/E). A good way to close this might be to open a PR on the user guide with the new process :-)

[jpmedley]

I thought we were trying to avoid tables because of the move to markdown. Also, this is reference material. Option 2 is scannable. Option 0 requires reading. Joe Medley | Technical Writer, Chrome DevRel | ***@***.*** | 816-678-7195 *If an API's not documented it doesn't exist.*

…

On Thu, Apr 29, 2021 at 7:13 PM Hamish Willee ***@***.***> wrote: I agree. (though I think a separate issue might be opened to agree properties documentation like in Math/E). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <mdn/content#4476 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB6S7C32N5TBRTPZMREMR6DTLIG6HANCNFSM43SKXBHA> .

[sideshowbarker]

I propose moving this to the Discussion tracker.

[Rumyra]

Adding a note to track this convo

[Ryuno-Ki]

Normally, GitHub places a „Subscribe” button in the right sidebar of an issue / PR / discussion, so to get notified without having to comment 👍 or similar :)

[Elchi3]

If there are no objections, I'd like to resolve this to option 0. No syntax sections for properties.

Done in mdn/content#8349

[hamishwillee]

I have no objection :-). So we can just strip them out now when we see them?

Kudos @Elchi3 for making a pragmatic decision. We might argue about this for months - fact is that this is much better than what is there, and there is no actual loss of information.

[estelle]

Objection!

Also, this is reference material. Option 2 is scannable. Option 0 requires
reading.

People don't read. They scan. They copy and paste from code, not from H1 or in-paragraph text.

Not sure why we went with 0 as most people liked 2.

I think #1 provides the most useful information, but #2 is scannable (people don't read) and easiert to ensure that authors will be able to include it for all properties (as opposed to useful examples, which are rare)

[Elchi3]

What do people scan, though? There isn't much syntax to scan with properties (unlike methods, where you scan the parameters).