Skip to content

[docs] Move settings doc tags from src/settings.js to tools/settings.py. NFC - #28343

Open
sbc100 wants to merge 1 commit into
emscripten-core:mainfrom
sbc100:settings-doc-tags
Open

sbc100 wants to merge 1 commit into
emscripten-core:mainfrom
sbc100:settings-doc-tags

Conversation

@sbc100

@sbc100 sbc100 commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Remove [link], [compile+link], [compile], [deprecated], and [experimental] tag comments from src/settings.js and generate those documentation notes in tools/maint/update_settings_docs.py directly from tools/settings.py.

This avoid duplicating information between the explicit list in settings.py and the tags in settings.js.

There used to be more value in having these tags in settings.js co-located with the setting, but these days the source of truth that folks should be referring too is the web site: https://emscripten.org/docs/tools_reference/settings_reference.html

See: #28311

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request refactors how settings metadata (such as compile-time, experimental, or deprecated status) is managed. It removes inline tags from "src/settings.js" and instead defines this metadata programmatically in "tools/settings.py", updating the documentation generator and link-time checks accordingly. A critical feedback item points out that the new type annotation "dict[str, str | None]" in "tools/settings.py" will cause runtime errors on Python versions older than 3.10, which violates Emscripten's compatibility requirements.

Comment thread tools/settings.py Outdated

EXPERIMENTAL_SETTINGS = {
# Experimental settings. Values with a message string also emit a warning at link time.
EXPERIMENTAL_SETTINGS: dict[str, str | None] = {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Using dict[str, str | None] as a type annotation will cause a TypeError at runtime on Python versions older than 3.10 (due to the | operator) and older than 3.9 (due to the use of dict as a generic). Since Emscripten supports Python 3.6+, this will break compatibility for users running older Python versions. It is safer to omit the type annotation or use typing.Dict and typing.Optional if type hinting is desired.

Suggested change
EXPERIMENTAL_SETTINGS: dict[str, str | None] = {
EXPERIMENTAL_SETTINGS = {

…gs.py`. NFC

Remove `[link]`, `[compile+link]`, `[compile]`, `[deprecated]`, and
`[experimental]` tag comments from `src/settings.js` and generate those
documentation notes in `tools/maint/update_settings_docs.py` directly
from `tools/settings.py`.

Add `COMPILE_ONLY_SETTINGS` (containing `INLINING_LIMIT`) so compile-only
settings stay distinguished from compile+link settings in Python without
changing generated docs.

See: emscripten-core#28311

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant