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

* Add standard sentence to properties with [LegacyNullToEmptyString]] * Add standard sentence to attributes with [LegacyNullToEmptyString]] * Add meta-info about [LegacyNullToEmptyString]] * Fix prose * Update files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md Co-authored-by: Ruth John <[email protected]> * Update files/en-us/web/api/canvasrenderingcontext2d/createpattern/index.md * Update files/en-us/web/api/window/open/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/window/open/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/element/innerhtml/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/domimplementation/createdocument/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/window/open/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/cssstyledeclaration/setproperty/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/window/open/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Add link in template * Update files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md * Update text * Update files/en-us/web/api/window/open/index.md Co-authored-by: Joshua Chen <[email protected]> * Apply suggestions from code review Co-authored-by: Joshua Chen <[email protected]> * Apply suggestions from code review --------- Co-authored-by: Ruth John <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Joshua Chen <[email protected]> Co-authored-by: Estelle Weyl <[email protected]> Co-authored-by: Estelle Weyl <[email protected]>
mdn · Jul 12, 2024 · 4656260 · 4656260
1 parent 5acf81a
commit 4656260
Show file tree

Hide file tree

Showing 21 changed files with 58 additions and 14 deletions.
diff --git a/...es/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md b/...es/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md
@@ -219,6 +219,18 @@ readonly attribute MediaError? error;
 
 The property value is an object of type `MediaError`. The question mark (`'?'`) indicates that it can take a value of `null`, and the documentation must explain _when_ this may occur. If no question mark is present, the `error` property can't be `null`.
 
+The type of the property may be prefixed with an _extended attribute_, a string enclosed in square brackets (like `[LegacyNullToEmptyString]`). Such extended attributes indicate special behaviors that must be described in the prose. Here is a list of standard extended attributes of types, and the addition that must be made:
+
+- `[LegacyNullToEmptyString]`
+
+  - : The `null` value is converted to a string in a non-standard way. The standard way is to convert it to the `"null"` string, but in this case, it is converted to `""`.
+
+    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 (`""`), so `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`._
+
+    The small inline example has to be adapted for each property.
+
 ### Writing permissions on the property
 
 ```webidl
@@ -348,6 +360,11 @@ TextTrack addTextTrack(TextTrackKind kind,
 
 The parameters of a method are listed in the Syntax section of the method sub-page. They are listed in the WebIDL in order, between the parenthesis, as a comma-separated list. Each parameter has a name (indicated above) and a type (e.g. a `'?'` means that the `null` value is valid.) If marked `optional`, the parameter is optional to include in a method call and must have the \\{{OptionalInline}} flag included when it is listed in the Syntax section. The parameter's default value is listed after the equality sign (`'='`).
 
+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 (`""`)._
+
 ### Type of the return value
 
 ```webidl

diff --git a/...ng_guidelines/page_structures/page_types/api_property_subpage_template/index.md b/...ng_guidelines/page_structures/page_types/api_property_subpage_template/index.md
@@ -93,6 +93,7 @@ Include a description of the property's value, including data type and what it r
 > A string representing...
 
 Note that some property pages are written in the form "Returns a [name of the property type] representing..." but this is not the recommended form.
+Also, some WebIDL extended attributes with specific meanings can be associated with the type. There are standard ways to document them; consult [Information contained in a WebIDL file](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#type_of_the_property) for more information.
 
 ## Examples
 

diff --git a/files/en-us/web/api/canvasrenderingcontext2d/createpattern/index.md b/files/en-us/web/api/canvasrenderingcontext2d/createpattern/index.md
@@ -45,7 +45,7 @@ createPattern(image, repetition)
     - `"repeat-y"` (vertical only)
     - `"no-repeat"` (neither direction)
 
-    If `repetition` is specified as an empty string (`""`) or [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) (but not {{jsxref("undefined")}}), a value of `"repeat"` will be used.
+    A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`): both are synonyms of `"repeat"`.
 
 ### Return value
 

diff --git a/files/en-us/web/api/characterdata/data/index.md b/files/en-us/web/api/characterdata/data/index.md
@@ -14,6 +14,8 @@ The **`data`** property of the {{domxref("CharacterData")}} interface represent
 
 A string with the character information contained in the {{domxref("CharacterData")}} node.
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `cd.data = null` is equivalent to `cd.data = ""`.
+
 ## Example
 
 > **Note:** {{domxref("CharacterData")}} is an abstract interface.

diff --git a/files/en-us/web/api/cssstyledeclaration/cssfloat/index.md b/files/en-us/web/api/cssstyledeclaration/cssfloat/index.md
@@ -16,6 +16,8 @@ When setting, it invokes {{DOMxRef("CSSStyleDeclaration.setProperty()")}} with `
 
 A string.
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `csd.cssFloat = null` is equivalent to `csd.cssFloat = ""`.
+
 ## Example
 
 In the below example, the stylesheet contains a single rule for `.box`, which has the {{cssxref("float")}} property with a value of `left`. This value will be returned by `cssFloat`. We then set the value to "right" using `cssFloat`, and return the new value.

diff --git a/files/en-us/web/api/cssstyledeclaration/setproperty/index.md b/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 (`""`).
     > **Note:** `value` must not contain `"!important"`, that should be set using the `priority` parameter.
 - `priority` {{optional_inline}}
 

diff --git a/files/en-us/web/api/document/alinkcolor/index.md b/files/en-us/web/api/document/alinkcolor/index.md
@@ -17,6 +17,8 @@ during the time between `mousedown` and `mouseup` events.
 
 A string containing the name of the color (e.g., `blue`, `darkblue`, etc.) or the hexadecimal value of the color (e.g., `#0000FF`).
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `document.alinkColor = null` is equivalent to `document.alinkColor = ""`.
+
 ## Notes
 
 The default value for this property in Mozilla Firefox is red (`#ee0000` in

diff --git a/files/en-us/web/api/document/bgcolor/index.md b/files/en-us/web/api/document/bgcolor/index.md
@@ -17,6 +17,8 @@ current document.
 
 A string representing the color as a word (e.g., "red") or hexadecimal value (e.g., "`#ff0000`").
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `document.bgColor = null` is equivalent to `document.bgColor = ""`.
+
 ## Examples
 
 ```js

diff --git a/files/en-us/web/api/document/linkcolor/index.md b/files/en-us/web/api/document/linkcolor/index.md
@@ -22,6 +22,8 @@ This property is deprecated. As an alternative, you can set the CSS
 
 A string representing the color as a word (e.g., `red`) or hexadecimal value (e.g., `#ff0000`).
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `document.linkColor = null` is equivalent to `document.linkColor = ""`.
+
 ## Examples
 
 ```js

diff --git a/files/en-us/web/api/document/vlinkcolor/index.md b/files/en-us/web/api/document/vlinkcolor/index.md
@@ -17,6 +17,8 @@ links that the user has visited in the document.
 
 A string representing the color as a word (e.g., `"red"`) or hexadecimal value (e.g., `"#ff0000"`).
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `document.vlinkColor = null` is equivalent to `document.vlinkColor = ""`.
+
 ## Notes
 
 - The default value for this property in Mozilla Firefox is purple

diff --git a/files/en-us/web/api/domimplementation/createdocument/index.md b/files/en-us/web/api/domimplementation/createdocument/index.md
@@ -14,18 +14,18 @@ returns an {{domxref("XMLDocument")}}.
 ## Syntax
 
 ```js-nolint
-createDocument(namespaceURI, qualifiedNameStr)
-createDocument(namespaceURI, qualifiedNameStr, documentType)
+createDocument(namespaceURI, qualifiedName)
+createDocument(namespaceURI, qualifiedName, documentType)
 ```
 
 ### Parameters
 
 - `namespaceURI`
   - : A string containing the namespace URI of the document to be
     created, or `null` if the document doesn't belong to one.
-- `qualifiedNameStr`
+- `qualifiedName`
   - : 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 (`""`).
 - `documentType` {{optional_inline}}
   - : Is the {{domxref("DocumentType")}} of the document to be created. It defaults to
     `null`.

diff --git a/files/en-us/web/api/element/innerhtml/index.md b/files/en-us/web/api/element/innerhtml/index.md
@@ -25,6 +25,8 @@ In order to set an element's contents from an HTML string that includes declarat
 A string containing the HTML serialization of the element's descendants.
 Setting the value of `innerHTML` removes all of the element's descendants and replaces them with nodes constructed by parsing the HTML given in the string _htmlString_.
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`.
+
 ### Exceptions
 
 - `SyntaxError` {{domxref("DOMException")}}

diff --git a/files/en-us/web/api/element/outerhtml/index.md b/files/en-us/web/api/element/outerhtml/index.md
@@ -25,6 +25,8 @@ Setting the value of `outerHTML` replaces the element and all of its
 descendants with a new DOM tree constructed by parsing the specified
 `htmlString`.
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.outerHTML = null` is equivalent to `elt.outerHTML = ""`.
+
 ### Exceptions
 
 - `SyntaxError` {{domxref("DOMException")}}

diff --git a/files/en-us/web/api/htmlfontelement/color/index.md b/files/en-us/web/api/htmlfontelement/color/index.md
@@ -27,6 +27,8 @@ The format of the string must follow one of the following HTML microsyntaxes (se
 
 A string.
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.color = null` is equivalent to `elt.color = ""`.
+
 ## Examples
 
 ```js

diff --git a/files/en-us/web/api/htmlimageelement/border/index.md b/files/en-us/web/api/htmlimageelement/border/index.md
@@ -34,7 +34,9 @@ For compatibility (or perhaps other) reasons, you can use the older properties i
 A string containing an integer value specifying the thickness of the
 border that should surround the image, in CSS pixels. A value of `0`, or an
 empty string, indicates that there should be no border drawn. The default value of
-`border` is `0`
+`border` is `0`.
+
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.border = null` is equivalent to `elt.border = ""`.
 
 ## Usage notes
 

diff --git a/files/en-us/web/api/htmltableelement/bgcolor/index.md b/files/en-us/web/api/htmltableelement/bgcolor/index.md
@@ -19,6 +19,8 @@ background color of the table.
 
 A string representing a color value.
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.bgColor = null` is equivalent to `elt.bgColor = ""`.
+
 ## Examples
 
 ```js

diff --git a/files/en-us/web/api/htmltableelement/cellpadding/index.md b/files/en-us/web/api/htmltableelement/cellpadding/index.md
@@ -15,7 +15,9 @@ padding around the individual cells of the table.
 
 ## Value
 
-A string representing pixels (e.g. "10") or a percentage value (e.g. "10%").
+A string representing pixels (e.g., `"10"`) or a percentage value (e.g., `"10%"`).
+
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.cellPadding = null` is equivalent to `elt.cellPadding = ""`.
 
 ## Examples
 

diff --git a/files/en-us/web/api/htmltableelement/cellspacing/index.md b/files/en-us/web/api/htmltableelement/cellspacing/index.md
@@ -19,8 +19,9 @@ representing a table's cells. Any two cells are separated by the sum of the
 
 ## Value
 
-A string which is either a number of pixels (such as
-`"10"`) or a percentage value (like `"10%"`).
+A string which is either a number of pixels (such as `"10"`) or a percentage value (like `"10%"`).
+
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.cellSpacing = null` is equivalent to `elt.cellSpacing = ""`.
 
 ## Examples
 

diff --git a/files/en-us/web/api/medialist/mediatext/index.md b/files/en-us/web/api/medialist/mediatext/index.md
@@ -24,10 +24,7 @@ different queries separated by commas, e.g. `screen, print`. Note that the
 `mediaText` will immediately update the behavior of the
 document.
 
-Also note that is you try to set
-`mediaText` to `null`, it will be treated as an empty
-string, i.e. the value will be set to
-`""`.
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `ml.mediaText = null` is equivalent to `ml.mediaText = ""`.
 
 ## Examples
 

diff --git a/files/en-us/web/api/shadowroot/innerhtml/index.md b/files/en-us/web/api/shadowroot/innerhtml/index.md
@@ -16,6 +16,8 @@ interface sets or returns a reference to the DOM tree inside the
 
 A string.
 
+When set to the `null` value, that `null` value is converted to the empty string (`""`), so `sr.innerHTML = null` is equivalent to `sr.innerHTML = ""`.
+
 ## Examples
 
 ```js

diff --git a/files/en-us/web/api/window/open/index.md b/files/en-us/web/api/window/open/index.md
@@ -84,6 +84,8 @@ open(url, target, windowFeatures)
     - `noreferrer`
       - : If this feature is set, the browser will omit the [`Referer`](/en-US/docs/Web/HTTP/Headers/Referer) header, as well as set `noopener` to true. See [`rel="noreferrer"`](/en-US/docs/Web/HTML/Attributes/rel/noreferrer) for more information.
 
+    A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`).
+
 > **Note:** Requested position (`top`, `left`), and requested dimension (`width`, `height`) values in `windowFeatures` **will be corrected** if any of such requested value does not allow the entire browser popup to be rendered within the work area for applications of the user's operating system. In other words, no part of the new popup can be initially positioned offscreen.
 
 ### Return value