Update deprecation messages for NodeFilter constants

[nberlette]

Description and Motivation

This pull request makes a minor wording update to the description of several legacy constants in the files/en-us/web/api/treewalker/index.md documentation.

The descriptions for NodeFilter.SHOW_ENTITY, NodeFilter.SHOW_ENTITY_REFERENCE, and NodeFilter.SHOW_NOTATION have been changed from "Legacy, no more usable." to "Legacy, no longer used.", clarifying their grammar and intent.

Additional details

N/A

Related issues and pull requests

[github-actions]

Preview URLs (6 pages)

• /en-US/docs/Web/API/Document/createNodeIterator
• /en-US/docs/Web/API/Document/createTreeWalker
• /en-US/docs/Web/API/NodeIterator/whatToShow
• /en-US/docs/Web/API/NodeIterator
• /en-US/docs/Web/API/TreeWalker/whatToShow
• /en-US/docs/Web/API/TreeWalker

(comment last updated: 2025-10-23 01:34:44)

[wbamberg]

Thanks for your PR!

This table is duplicated in https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/whatToShow. I think it would be better to delete the table from TreeWalker, and update the one in TreeWalker/whatToShow.

[nberlette]

I totally agree; I'll drop the duplicate table and push the changes in the next hour or so.

Quick question for you — is the table also present in the NodeIterator page? If so, would it be feasible to instead house the table data in a single location (i.e., a "partial" file) and include it in each page that depends on it? Seems much more maintainable to me, but I'm not too familiar with the inner workings of the MDN / yari systems.

Thanks for your time and feedback!!

[Josh-Cena]

If so, would it be feasible to instead house the table data in a single location (i.e., a "partial" file) and include it in each page that depends on it?

This capability has been removed because it makes the build system significantly more complicated. You should either copy the table (generally discouraged), or just link to it like "for more information, see xxx (anchor link to the section)".

[wbamberg]

Quick question for you — is the table also present in the NodeIterator page? If so, would it be feasible to instead house the table data in a single location (i.e., a "partial" file) and include it in each page that depends on it? Seems much more maintainable to me, but I'm not too familiar with the inner workings of the MDN / yari systems.

This is tricky. Like Josh says, no, we don't have a general mechanism for this in MDN. The way this usually gets handled in MDN is that there's a page for the interface that defines the constant values, and places that use them can link to it. See for instance KeyboardEvent. But here, the interface that defines the constants is NodeFilter, which doesn't have a page on MDN, because it doesn't implement any methods that a developer calls (it's a callback interface). So we don't have a great place to keep a single copy which the other places can link to.

We could add a page for NodeFilter, but I'm not sure it's worth it.

If it were me, I think I would do one of the following:

1. have just 2 copies of the table, one at https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/whatToShow and the other at https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/whatToShow
2. have just one copy, at https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/whatToShow, and have everything else link there. This is a little wonky because https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/whatToShow isn't a perfect home for it, but it avoids any duplication, so it would probably be my preference.

[Josh-Cena]

Actually, following #38254 and #28944, we should remove the deprecation because the spec doesn't mention anything about deprecation.

This table is present in six places: document.createNodeIterator(), document.createTreeWalker(), NodeIterator, NodeIterator.whatToShow, TreeWalker, TreeWalker.whatToShow. Currently, the first two pages have the deprecation gone, but all the other four still have them.

[Josh-Cena]

@wbamberg Could you take another look? Consolidated them into two tables

[wbamberg]

This looks great. I made a tiny editorial comment which you can accept if you like, but approving anyway. Thanks @nberlette and @Josh-Cena !