diff --git a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md index c965ada64d46a5a..2a7107139896b7b 100644 --- a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md +++ b/files/en-us/mdn/writing_guidelines/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/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md index cdec1cea989d8a7..7357f1285da9395 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md +++ b/files/en-us/mdn/writing_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 index 819abea743137a5..d4665175fec98d5 100644 --- 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 index c9d7a37e1ca4f4e..7c658e936aa1316 100644 --- 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 index 6abd1d0ba165601..d635df47717092e 100644 --- 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 index 6d9b741de86b14a..6d092a51f0a775d 100644 --- 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 index eb381acc703867c..98b973db6421c7c 100644 --- 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 index dbed462383dc5dd..1d6da94b2daa768 100644 --- 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 index 40b263f0dcae595..4d98565962fe534 100644 --- 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 index b430d9e9790d0e5..ab0abec355e31c6 100644 --- 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 index ca4b073b23b06b4..466c6df68a7d08c 100644 --- a/files/en-us/web/api/domimplementation/createdocument/index.md +++ b/files/en-us/web/api/domimplementation/createdocument/index.md @@ -14,8 +14,8 @@ returns an {{domxref("XMLDocument")}}. ## Syntax ```js-nolint -createDocument(namespaceURI, qualifiedNameStr) -createDocument(namespaceURI, qualifiedNameStr, documentType) +createDocument(namespaceURI, qualifiedName) +createDocument(namespaceURI, qualifiedName, documentType) ``` ### Parameters @@ -23,9 +23,9 @@ createDocument(namespaceURI, qualifiedNameStr, documentType) - `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 index 7a352ea69633eec..491b3dda4390677 100644 --- 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 index 14ae5f6428879a1..ce245285370324e 100644 --- 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 index 609e0f228d64953..89d723ae68e4177 100644 --- 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 index 05c1f010e8907eb..6cee899d2355aee 100644 --- 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 index dcd258ab5fc292c..be9829c40417e0b 100644 --- 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 index 6f583f3f58ca83c..f247ea394e1c755 100644 --- 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 index f14e027ec77c581..d6c72b76bd13227 100644 --- 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 index 526d8b4c7b664b8..bc83cd72fc2b5d8 100644 --- 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 index 1fcaf1cd903f7c6..ea55fd8ec58d7d4 100644 --- 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 index 4d87fc4d54324d7..3d5032ea7ca2981 100644 --- 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