Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add page types for the WebAssembly section #27737

Merged
merged 4 commits into from
Nov 3, 2023
Merged

Add page types for the WebAssembly section #27737

merged 4 commits into from
Nov 3, 2023

Conversation

teoli2003
Copy link
Contributor

@teoli2003 teoli2003 commented Jul 4, 2023 •
edited
Loading

This adds page types for WebAssembly. I tried to stay as close as possible as the Web APIs page types for the JS API. There are also guide and landing-page, as well as webassembly-instruction for the pages with opcodes.

  • webassembly-function: a global function, that is a method directly under the WebAssembly object that acts as a namespace, like WebAssembly.instantiate().
  • webassembly-constructor: a constructor, like WebAssembly.Exception().
  • webassembly-interface: a WebAssembly interface, like WebAssembly.LinkError.
  • webassembly-instance-property: an instance property, like WebAssembly.Instance.exports.
  • webassembly-instance-method: an instance method, like WebAssembly.Exception.getArg().
  • webassembly-static-method: a static method, like WebAssembly.Module.exports().
  • webassembly-instruction: an instruction, or a set of instructions, like Wrap.

This is a part of openwebdocs/project#91

@teoli2003 teoli2003 requested a review from Elchi3 July 4, 2023 06:34
@teoli2003 teoli2003 requested review from a team as code owners July 4, 2023 06:34
@github-actions github-actions bot added Content:wasm WebAssembly docs Content:Meta Content in the meta docs labels Jul 4, 2023
@teoli2003 teoli2003 changed the title Pagetypes webassembly Add page types for the WebAssembly section Jul 4, 2023
@github-actions
Copy link
Contributor

github-actions bot commented Jul 4, 2023 •
edited
Loading

Preview URLs (117 pages)
Flaws (5)

Note! 114 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/WebAssembly/JavaScript_interface/instantiate
Title: WebAssembly.instantiate()
Flaw count: 1

  • broken_links:
    • Can't resolve /en-US/docs/WebAssembly/Caching_modules

URL: /en-US/docs/WebAssembly/Reference
Title: WebAssembly instruction reference
Flaw count: 3

  • broken_links:
    • Can't resolve /en-US/docs/WebAssembly/Reference/Vector
    • Can't resolve /en-US/docs/WebAssembly/Reference/Reference
    • Can't resolve /en-US/docs/WebAssembly/Reference/Table

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Page_type_key
Title: The page-type front matter key
Flaw count: 1

  • broken_links:
    • Can't resolve /en-US/docs/WWeb/XSLT/Element/message

(comment last updated: 2023-11-03 00:21:20)

@Elchi3
Copy link
Member

Elchi3 commented Jul 10, 2023

  • webassembly-function: a global function, that is a method directly under the WebAssembly object that acts as a namespace, like WebAssembly.instantiate().

This seems worth talking about. In the JS docs we have the page-types javascript-namespace and the methods are of page-type javascript-static-method. In API docs, there is web-api-interface and web-api-static-method.

So, this would introduce a third way of dealing with namespaces. Ideally, we agree on one way to have page-types for namespaces ...

See also the discussion in BCD mdn/browser-compat-data#20114

@Elchi3 Elchi3 requested a review from wbamberg July 19, 2023 10:37
@wbamberg
Copy link
Collaborator

  • webassembly-function: a global function, that is a method directly under the WebAssembly object that acts as a namespace, like WebAssembly.instantiate().

This seems worth talking about. In the JS docs we have the page-types javascript-namespace and the methods are of page-type javascript-static-method. In API docs, there is web-api-interface and web-api-static-method.

So, this would introduce a third way of dealing with namespaces. Ideally, we agree on one way to have page-types for namespaces ...

See also the discussion in BCD mdn/browser-compat-data#20114

Unless I'm misreading this:

a method directly under the WebAssembly object that acts as a namespace

...it doesn't mean instantiate() acts as a namespace, it means WebAssembly acts as a namespace. The sentence is ambiguous though, it would be clearer just to omit "that acts as a namespace". So webassembly-function is more like an analog for web-api-global-function.

There is an issue here though I think. If the WebAssembly JS docs were still in JavaScript I would probably have made WebAssembly a javascript-namespace, like Intl. But in this proposal WebAssembly is a landing-page. I'm not keen on that, because WebAssembly is a concrete thing, so should get a referency page type. A landing page isn't a docs page for a thing, it's really a nav item, like a sidebar - that is, it's an abstraction.

But if WebAssembly is a javascript-namespace then we have JS page types outside /JavaScript. Is that OK? If so, does that also mean that webassembly-instance-method should instead be javascript-instance-method?

Or, since https://github.com/orgs/mdn/discussions/151 suggests that they are more like Web APIs, would it be better to borrow page types from Web/API instead?

@Elchi3
Copy link
Member

Elchi3 commented Jul 21, 2023

Thanks Will.

I think I am +1 on treating this like a Web API.

Note that Web APIs have no namespace page type and whether they should is discussed in mdn/browser-compat-data#20114. If we assume Web APIs get no "namespace" page-type, then I think it would be like this:

WebAssembly: web-api-interface (could be web-api-namespace, see the BCD discussion)
WebAssembly.instantiate(): web-api-static-method
WebAssembly.LinkError: web-api-interface
WebAssembly.Instance.exports: web-api-instance-property
WebAssembly.Exception.getArg(): web-api-instance-method
WebAssembly.Module.exports(): web-api-static-method

For statics, I guess _static should be used in slugs then.

@Josh-Cena
Copy link
Member

They should definitely be webassembly-* and not either javascript-* or web-api-*. They are implemented by the JavaScript engine, not the browser, so they should not be web-api-*, and they are not specced by TC39 either (see the discussion before moving the WebAssembly reference from JS docs to Wasm docs)

caugner
caugner approved these changes Oct 16, 2023
View reviewed changes
Copy link
Contributor

@caugner caugner left a comment

Choose a reason for hiding this comment

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

Naming and (config) changes LGTM, but I defer to those with more context to align on final names. Prefixing these types with webassembly- sounds like a good idea to me.

@github-actions github-actions bot added the system [PR only] Infrastructure and configuration for the project label Nov 2, 2023
@wbamberg wbamberg merged commit c681ed8 into mdn:main Nov 3, 2023
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@caugner caugner caugner approved these changes

@wbamberg wbamberg wbamberg approved these changes

@Elchi3 Elchi3 Awaiting requested review from Elchi3

Assignees
No one assigned
Labels
Content:Meta Content in the meta docs Content:wasm WebAssembly docs system [PR only] Infrastructure and configuration for the project
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@teoli2003 @Elchi3 @wbamberg @Josh-Cena @caugner