Skip to content

Commit 30ae43a

Browse files
nberletteJosh-Cenawbamberg
authored
Update deprecation messages for NodeFilter constants (#41122)
* docs(nodefilter): update deprecation messages for NodeFilter constants This commit updates the `NodeFilter` descriptions for the deprecated/legacy flags, clarifying their grammar and intent. * Remove extra tables * Apply suggestions from code review Co-authored-by: wbamberg <[email protected]> --------- Co-authored-by: Joshua Chen <[email protected]> Co-authored-by: wbamberg <[email protected]>
1 parent a55af8a commit 30ae43a

File tree

6 files changed

+23
-249
lines changed

6 files changed

+23
-249
lines changed

‎files/en-us/web/api/document/createnodeiterator/index.md‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -29,21 +29,24 @@ createNodeIterator(root, whatToShow, filter)
2929
It is a convenient way of filtering for certain types of node. It defaults to
3030
`0xFFFFFFFF` representing the `SHOW_ALL` constant.
3131

32-
| Constant | Numerical value | Description |
33-
| -------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34-
| `NodeFilter.SHOW_ALL` | `4294967295` (that is the max value of `unsigned long`) | Shows all nodes. |
35-
| `NodeFilter.SHOW_ATTRIBUTE` | `2` | Shows attribute {{ domxref("Attr") }} nodes. This is meaningful only when creating a {{ domxref("TreeWalker") }} with an {{ domxref("Attr") }} node as its root. In this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree. |
36-
| `NodeFilter.SHOW_CDATA_SECTION` | `8` | Shows {{ domxref("CDATASection") }} nodes. |
37-
| `NodeFilter.SHOW_COMMENT` | `128` | Shows {{ domxref("Comment") }} nodes. |
38-
| `NodeFilter.SHOW_DOCUMENT` | `256` | Shows {{ domxref("Document") }} nodes. |
39-
| `NodeFilter.SHOW_DOCUMENT_FRAGMENT` | `1024` | Shows {{ domxref("DocumentFragment") }} nodes. |
40-
| `NodeFilter.SHOW_DOCUMENT_TYPE` | `512` | Shows {{ domxref("DocumentType") }} nodes. |
41-
| `NodeFilter.SHOW_ELEMENT` | `1` | Shows {{ domxref("Element") }} nodes. |
42-
| `NodeFilter.SHOW_ENTITY` {{deprecated_inline}} | `32` | Legacy, no more usable. |
43-
| `NodeFilter.SHOW_ENTITY_REFERENCE` {{deprecated_inline}} | `16` | Legacy, no more usable. |
44-
| `NodeFilter.SHOW_NOTATION` {{deprecated_inline}} | `2048` | Legacy, no more usable. |
45-
| `NodeFilter.SHOW_PROCESSING_INSTRUCTION` | `64` | Shows {{ domxref("ProcessingInstruction") }} nodes. |
46-
| `NodeFilter.SHOW_TEXT` | `4` | Shows {{ domxref("Text") }} nodes. |
32+
| Constant | Numerical value | Description |
33+
| -------------------------------------------------------- | --------------- | ------------------------------------------------- |
34+
| `NodeFilter.SHOW_ALL` | `0xFFFFFFFF` | Shows all nodes. |
35+
| `NodeFilter.SHOW_ATTRIBUTE` | `0x2` | Shows {{domxref("Attr")}} nodes. |
36+
| `NodeFilter.SHOW_CDATA_SECTION` | `0x8` | Shows {{domxref("CDATASection")}} nodes. |
37+
| `NodeFilter.SHOW_COMMENT` | `0x80` | Shows {{domxref("Comment")}} nodes. |
38+
| `NodeFilter.SHOW_DOCUMENT` | `0x100` | Shows {{domxref("Document")}} nodes. |
39+
| `NodeFilter.SHOW_DOCUMENT_FRAGMENT` | `0x400` | Shows {{domxref("DocumentFragment")}} nodes. |
40+
| `NodeFilter.SHOW_DOCUMENT_TYPE` | `0x200` | Shows {{domxref("DocumentType")}} nodes. |
41+
| `NodeFilter.SHOW_ELEMENT` | `0x1` | Shows {{domxref("Element")}} nodes. |
42+
| `NodeFilter.SHOW_ENTITY` {{deprecated_inline}} | `0x20` | Legacy, no longer effective. |
43+
| `NodeFilter.SHOW_ENTITY_REFERENCE` {{deprecated_inline}} | `0x10` | Legacy, no longer effective. |
44+
| `NodeFilter.SHOW_NOTATION` {{deprecated_inline}} | `0x800` | Legacy, no longer effective. |
45+
| `NodeFilter.SHOW_PROCESSING_INSTRUCTION` | `0x40` | Shows {{domxref("ProcessingInstruction")}} nodes. |
46+
| `NodeFilter.SHOW_TEXT` | `0x4` | Shows {{domxref("Text")}} nodes. |
47+
48+
> [!NOTE]
49+
> The `NodeFilter.SHOW_ATTRIBUTE` constant is only effective when the root is an attribute node. Since the parent of any `Attr` node is always `null`, {{DOMXref("TreeWalker.nextNode()")}} and {{DOMXref("TreeWalker.previousNode()")}} will never return an `Attr` node. To traverse `Attr` nodes, use {{DOMXref("Element.attributes")}} instead.
4750
4851
- `filter` {{optional_inline}}
4952
- : A callback function or an object with an `acceptNode()` method. The function or method will be called for each node in the subtree based at root which is accepted as included by the whatToShow flag to determine whether or not to include it in the list of iterable nodes. The method should return one of `NodeFilter.FILTER_ACCEPT`, `NodeFilter.FILTER_REJECT`, or `NodeFilter.FILTER_SKIP`. See the [Example](#examples).

‎files/en-us/web/api/document/createtreewalker/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ createTreeWalker(root, whatToShow, filter)
4343
| `NodeFilter.SHOW_TEXT` | `0x4` | Shows {{domxref("Text")}} nodes. |
4444

4545
> [!NOTE]
46-
> Since the parent of any `Attr` node is always `null`, {{DOMXref("TreeWalker.nextNode()")}} and {{DOMXref("TreeWalker.previousNode()")}} will never return an `Attr` node. To traverse `Attr` nodes, use {{DOMXref("Element.attributes")}} instead.
46+
> The `NodeFilter.SHOW_ATTRIBUTE` constant is only effective when the root is an attribute node. Since the parent of any `Attr` node is always `null`, {{DOMXref("TreeWalker.nextNode()")}} and {{DOMXref("TreeWalker.previousNode()")}} will never return an `Attr` node. To traverse `Attr` nodes, use {{DOMXref("Element.attributes")}} instead.
4747
4848
- `filter` {{optional_inline}}
4949
- : A callback function or an object with an `acceptNode()` method, which returns `NodeFilter.FILTER_ACCEPT`, `NodeFilter.FILTER_REJECT`, or `NodeFilter.FILTER_SKIP`. The function or method will be called for each node in the subtree based at `root` which is accepted as included by the `whatToShow` flag to determine whether or not to include it in the list of iterable nodes:

‎files/en-us/web/api/nodeiterator/index.md‎

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -25,25 +25,6 @@ _This interface doesn't inherit any property._
2525
- {{domxref("NodeIterator.whatToShow")}} {{ReadOnlyInline}}
2626
- : Returns an `unsigned long` bitmask that describes the types of {{domxref("Node")}}
2727
to be matched. Non-matching nodes are skipped, but relevant child nodes may be included.
28-
29-
The possible bitmask values are constants from the `NodeFilter` interface:
30-
31-
| Constant | Numerical value | Description |
32-
| -------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33-
| `NodeFilter.SHOW_ALL` | `4294967295` (that is the max value of `unsigned long`) | Shows all nodes. |
34-
| `NodeFilter.SHOW_ATTRIBUTE` {{deprecated_inline}} | `2` | Shows attribute {{ domxref("Attr") }} nodes. This is meaningful only when creating a `NodeIterator` with an {{ domxref("Attr") }} node as its root; in this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree. |
35-
| `NodeFilter.SHOW_CDATA_SECTION` {{deprecated_inline}} | `8` | Shows {{ domxref("CDATASection") }} nodes. |
36-
| `NodeFilter.SHOW_COMMENT` | `128` | Shows {{ domxref("Comment") }} nodes. |
37-
| `NodeFilter.SHOW_DOCUMENT` | `256` | Shows {{ domxref("Document") }} nodes. |
38-
| `NodeFilter.SHOW_DOCUMENT_FRAGMENT` | `1024` | Shows {{ domxref("DocumentFragment") }} nodes. |
39-
| `NodeFilter.SHOW_DOCUMENT_TYPE` | `512` | Shows {{ domxref("DocumentType") }} nodes. |
40-
| `NodeFilter.SHOW_ELEMENT` | `1` | Shows {{ domxref("Element") }} nodes. |
41-
| `NodeFilter.SHOW_ENTITY` {{deprecated_inline}} | `32` | Legacy, no longer used. |
42-
| `NodeFilter.SHOW_ENTITY_REFERENCE` {{deprecated_inline}} | `16` | Legacy, no longer used. |
43-
| `NodeFilter.SHOW_NOTATION` {{deprecated_inline}} | `2048` | Legacy, no longer used. |
44-
| `NodeFilter.SHOW_PROCESSING_INSTRUCTION` | `64` | Shows {{domxref("ProcessingInstruction")}} nodes. |
45-
| `NodeFilter.SHOW_TEXT` | `4` | Shows {{domxref("Text") }} nodes. |
46-
4728
- {{domxref("NodeIterator.filter")}} {{ReadOnlyInline}}
4829
- : Returns a `NodeFilter` used to select the relevant nodes.
4930
- {{domxref("NodeIterator.referenceNode")}} {{ReadOnlyInline}}

0 commit comments

Comments
 (0)