Should string values values in JavaScript be documented with quotes in reference.

[hamishwillee]

The API reference documents string values inconsistently, with quote around the strings, and without. What do people prefer?

Note:

• The templates don't say which is preferred
• My sense is that far mor cases omit the strings.
• Some prefer with the quotes, as it is immediately obvious they are strings
• Others don't, because what else could they be in the given context, especially after you just said? Extra key presses are annoying.

No quotes

An {{jsxref("Array")}} of strings representing blah.
Values may include:

• someValue
  • : The blah blah
• anotherValue
  • : The blah blah

With quotes

An {{jsxref("Array")}} of strings representing blah.
Values may include:

• "someValue"
  • : The blah blah
• "anotherValue"
  • : The blah blah

[Josh-Cena]

If "I prefer no rule as in the status quo and let me decide based on context" is an opinion you are willing to hear, then let that be it; otherwise I prefer quotes to none, because if we ever have non-string values like null, false, or 1, we don't get any ambiguity. This seems to be the current majority of cases in JS docs.

[TabassumBabar]

If there’s flexibility ("no rule"), you’d prefer deciding based on context.

But if a standard must be chosen, you lean toward always quoting keys to avoid ambiguity, aligning with the majority of current JavaScript documentation practices.

This approach strikes a balance between flexibility and consistency, ensuring that your code remains unambiguous and compatible across different environments and tools

[OnkarRuikar]

+1 to having something to distinguish between strings and other values. A glance tells you it's a string; you don't have to look around.

Our code formatter uses ", so the same should be used for regular and definition lists. We need to convert single quotes to double quotes for consistency:

• https://github.com/mdn/content/blob/main/files/en-us/web/api/contactsmanager/getproperties/index.md?plain=1#L34-L38
• https://github.com/mdn/content/blob/main/files/en-us/web/api/serviceworkercontainer/register/index.md?plain=1#L59-L76
• ...

[bsmth]

We need to convert single quotes to double quotes for consistency

I'm sorry I misread that. No objections really, although do we have an estimate of how many places this would require being updated?

[hamishwillee]

FWIW, there are specific cases where single quotes are required in some docs - i.e in CSP you might have https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#none

[OnkarRuikar]

FWIW, there are specific cases where single quotes are required in some docs - i.e in CSP you might have developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#none

@hamishwillee I think "'none'" would be more correct as they've done in the specs: https://w3c.github.io/webappsec-csp/#directive-frame-ancestors
The 'none' is a whole thing in CSP, including the single quotes. It is not just the none word.

[Josh-Cena]

In HTTP there's nothing other than a "string", so any extra quotes are redundant. We are only talking about JavaScript values where "1" and 1 are meaningfully different.

[hamishwillee]

Sure, I just wanted to make sure any linting didn't swap these cases to double quotes.