Add prose and meta-docs for [LegacyNullToEmptyString] #28213

teoli2003 · 2023-07-27T10:08:26Z

Description

This PR adds relevant information to existing MDN pages about properties or method parameters prefixed with the WebIDL [LegacyNullToEmptyString].

Motivation

This is part of openwebdocs/project#159 where we want to uniformize and add more information stored in WebIDLs files. Standardizing them makes them easier to understand and MDN Web docs articles more precise.

Additional details

What does this extended attribute mean?

This extended attribute alters how null values are converted to a string. The standard way is to convert null to the string "null". When this extended attribute is present, the null object is converted to an empty string ("").

What does this PR do?

It adds to all relevant properties a sentence explaining the set behaviour when set to the null value, with a tiny inline example.
It adds to all such parameters a sentence explaining what the behaviour is when null is passed.
Update the meta-docs, listing the standardized sentences.

Related issues and pull requests

None.

github-actions · 2023-07-27T10:10:39Z

Preview URLs (21 pages)

(comment last updated: 2024-01-10 12:27:57)

wbamberg · 2023-07-27T23:38:55Z

...ting_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md

+
+    Add the following sentence to the end of the _Value_ section of the article:
+
+    _When set to the `null` value, that `null` value is converted to the empty string (`""`), unlike the common behavior with strings (that would have converted it to the `"null"` string): `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`._


I think it would be worth simplifying and shortening this:

Suggested change

_When set to the `null` value, that `null` value is converted to the empty string (`""`), unlike the common behavior with strings (that would have converted it to the `"null"` string): `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`._

_When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`._

So I'm not sure it's worth describing what doesn't happen, just what does happen.

Also I think it's worth adding this meta-guidance (or at least a link to it) to our page templates, since that's the main place people go to figure out how to write reference pages.

I've added a link in the template.

files/en-us/web/api/canvasrenderingcontext2d/createpattern/index.md

files/en-us/web/api/domimplementation/createdocument/index.md

...ting_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md

Rumyra · 2023-08-02T08:37:19Z

All looks good to me! Agree with @wbamberg suggestions and one nit :)

wbamberg · 2023-10-25T05:44:03Z

@teoli2003 , are you coming back to this, or should we close it for now?

bsmth · 2024-01-10T10:51:01Z

Hi @teoli2003 shall we close this for now?

files/en-us/web/api/cssstyledeclaration/setproperty/index.md

files/en-us/web/api/domimplementation/createdocument/index.md

files/en-us/web/api/element/innerhtml/index.md

files/en-us/web/api/window/open/index.md

...ting_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md

…e/information_contained_in_a_webidl_file/index.md Co-authored-by: Ruth John <Rumyra@users.noreply.github.com>

…ex.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

…e/information_contained_in_a_webidl_file/index.md

teoli2003 · 2024-01-10T12:27:55Z

Hi @teoli2003 shall we close this for now?

I have fixed all open points and rebased. Let's ask for a re-review.

Josh-Cena · 2024-01-13T04:06:08Z

files/en-us/web/api/cssstyledeclaration/setproperty/index.md

@@ -25,7 +25,7 @@ setProperty(propertyName, value, priority)
  - : A string representing the CSS property name (hyphen case) to be modified.
 - `value` {{optional_inline}}
  - : A string containing the new property value. If not specified, treated
-    as the empty string.
+    as the empty string. A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).


Suggested change

as the empty string. A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).

as the empty string. A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).

Also, shouldn't this be merged with the previous sentence? "If null or unspecified, it is treated the same as the empty string ("")"

Josh-Cena · 2024-01-13T04:06:42Z

...ting_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md

+Parameter types may have special behaviors described using extended attributes (like `[LegacyNullToEmptyString]`). Here is the list of such attributes, and the addition you have to do in the prose:
+
+- `[LegacyNullToEmptyString]`
+  - : Add the following sentence at the end of the parameter description: _A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`)._


Suggested change

- : Add the following sentence at the end of the parameter description: _A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`)._

- : Add the following sentence at the end of the parameter description: _A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`)._

Josh-Cena · 2024-01-13T04:08:22Z

files/en-us/web/api/domimplementation/createdocument/index.md

  - : A string containing the qualified name, that is an optional
-    prefix and colon plus the local root element name, of the document to be created.
+    prefix and colon plus the local root element name, of the document to be created. A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).


Suggested change

prefix and colon plus the local root element name, of the document to be created. A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).

prefix and colon plus the local root element name, of the document to be created. A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).

files/en-us/web/api/window/open/index.md

github-actions · 2024-05-02T05:39:04Z

This pull request has merge conflicts that must be resolved before it can be merged.

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

github-actions bot added Content:WebAPI Web API docs Content:Meta Content in the meta docs labels Jul 27, 2023

teoli2003 mentioned this pull request Jul 27, 2023

OWD project: Doc structures for WebIDL concepts openwebdocs/project#159

Open

6 tasks

teoli2003 requested review from Rumyra, Elchi3, wbamberg and Josh-Cena July 27, 2023 10:19

teoli2003 marked this pull request as ready for review July 27, 2023 10:19

teoli2003 requested review from a team as code owners July 27, 2023 10:19

wbamberg reviewed Jul 27, 2023

View reviewed changes

files/en-us/web/api/canvasrenderingcontext2d/createpattern/index.md Outdated Show resolved Hide resolved

files/en-us/web/api/domimplementation/createdocument/index.md Outdated Show resolved Hide resolved

Rumyra requested changes Aug 2, 2023

View reviewed changes

...ting_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md Outdated Show resolved Hide resolved

bsmth added the awaiting response Awaiting for author to address review/feedback label Jan 10, 2024

github-actions bot reviewed Jan 10, 2024

View reviewed changes

teoli2003 commented Jan 10, 2024

View reviewed changes

...ting_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md Outdated Show resolved Hide resolved

teoli2003 and others added 10 commits January 10, 2024 13:25

Add standard sentence to properties with [LegacyNullToEmptyString]]

d298448

Add standard sentence to attributes with [LegacyNullToEmptyString]]

1029ffd

Add meta-info about [LegacyNullToEmptyString]]

e20793d

Fix prose

70f7864

Update files/en-us/mdn/writing_guidelines/howto/write_an_api_referenc…

ae1032f

…e/information_contained_in_a_webidl_file/index.md Co-authored-by: Ruth John <Rumyra@users.noreply.github.com>

Update files/en-us/web/api/canvasrenderingcontext2d/createpattern/ind…

5117429

…ex.md

Update files/en-us/web/api/window/open/index.md

a863e62

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/api/window/open/index.md

5240c82

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/api/element/innerhtml/index.md

1f4c3a2

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/api/domimplementation/createdocument/index.md

86e7ef8

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

teoli2003 and others added 6 commits January 10, 2024 13:25

Update files/en-us/web/api/window/open/index.md

06ae4bc

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/api/cssstyledeclaration/setproperty/index.md

43545f3

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/api/window/open/index.md

643dc5f

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Add link in template

c8bb3fa

Update files/en-us/mdn/writing_guidelines/howto/write_an_api_referenc…

15bd5a3

…e/information_contained_in_a_webidl_file/index.md

Update text

33a322b

teoli2003 force-pushed the LegacyNullToEmptyString branch from 20f91aa to 33a322b Compare January 10, 2024 12:26

teoli2003 removed the awaiting response Awaiting for author to address review/feedback label Jan 10, 2024

teoli2003 requested review from wbamberg and Rumyra January 10, 2024 12:28

Josh-Cena reviewed Jan 13, 2024

View reviewed changes

github-actions bot added the merge conflicts 🚧 label May 2, 2024

Update files/en-us/web/api/window/open/index.md

241dbac

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

github-actions bot added the size/m 51-500 LoC changed label May 2, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add prose and meta-docs for [LegacyNullToEmptyString] #28213

Add prose and meta-docs for [LegacyNullToEmptyString] #28213

teoli2003 commented Jul 27, 2023

github-actions bot commented Jul 27, 2023 •

edited

wbamberg Jul 27, 2023 •

edited

teoli2003 Jan 10, 2024

Rumyra commented Aug 2, 2023

wbamberg commented Oct 25, 2023

bsmth commented Jan 10, 2024

teoli2003 commented Jan 10, 2024

Josh-Cena Jan 13, 2024

Josh-Cena Jan 13, 2024

Josh-Cena Jan 13, 2024

github-actions bot commented May 2, 2024


		Add the following sentence to the end of the _Value_ section of the article:

		_When set to the `null` value, that `null` value is converted to the empty string (`""`), unlike the common behavior with strings (that would have converted it to the `"null"` string): `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`._

	as the empty string. A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).
	as the empty string. A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).

	- : Add the following sentence at the end of the parameter description: _A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`)._
	- : Add the following sentence at the end of the parameter description: _A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`)._

	prefix and colon plus the local root element name, of the document to be created. A ["null"](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).
	prefix and colon plus the local root element name, of the document to be created. A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).

Add prose and meta-docs for [LegacyNullToEmptyString] #28213

Are you sure you want to change the base?

Add prose and meta-docs for [LegacyNullToEmptyString] #28213

Conversation

teoli2003 commented Jul 27, 2023

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Jul 27, 2023 • edited

wbamberg Jul 27, 2023 • edited

Choose a reason for hiding this comment

teoli2003 Jan 10, 2024

Choose a reason for hiding this comment

Rumyra commented Aug 2, 2023

wbamberg commented Oct 25, 2023

bsmth commented Jan 10, 2024

teoli2003 commented Jan 10, 2024

Josh-Cena Jan 13, 2024

Choose a reason for hiding this comment

Josh-Cena Jan 13, 2024

Choose a reason for hiding this comment

Josh-Cena Jan 13, 2024

Choose a reason for hiding this comment

github-actions bot commented May 2, 2024

github-actions bot commented Jul 27, 2023 •

edited

wbamberg Jul 27, 2023 •

edited