api.CSS namespace functions - why static?

[saschanaz]

What type of issue is this?

Other

What information was incorrect, unhelpful, or incomplete?

Namespaces cannot have non-static members, not sure the value to put it with _static.

This also does not match what console and WebAssembly have, for example.

What browsers does this problem apply to, if applicable?

No response

What did you expect to see?

api.CSS.Hz etc.

Did you test this? If so, how?

browser-compat-data/api/CSS.json

Line 38 in 3b048d4

"Hz_static": {

Can you link to any release notes, bugs, pull requests, or MDN pages related to this?

#16613

Do you have anything more you want to share?

No response

MDN URL

No response

MDN metadata

No response

[Elchi3]

Yeah, I wasn't sure about this. I followed the MDN doc structures which also have _static https://developer.mozilla.org/en-US/docs/Web/API/CSS.

Maybe that is outdated thinking, though. The spec says:

This was previously specified as an IDL interface that only held static methods. Switching to an IDL namespace is nearly identical, so it’s expected that there won’t be any compat concerns. If any are discovered, please report so we can consider reverting this change.

[foolip]

I don't think we should use the _static suffix for namespaces, because there are no methods or attributes that need a this, it's all static in a sense.

[saschanaz]

Maybe that is outdated thinking, though. The spec says:

I think that can go, the switch happened several years ago and it's unlikely to be reverted at this point.

[saschanaz]

Another thing is WebAssembly.Module, which is namespace-y but is an interface, and MDN does not use _static. Should we use _static here? For IDL purpose, consistency is very appreciated.

• https://webassembly.github.io/spec/js-api/#module
• https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Module/customSections

[Elchi3]

I'm happy to revert the change to api.CSS but I think MDN should then also follow that. cc @wbamberg in case there were thoughts about namespaces and statics and MDN page-types.

Generally, I think it makes sense to do what is in IDL. So if WebAssembly.Module is an interface then let's apply the _static rule there, too.

Probably also makes sense to write this up as a guideline.

[wbamberg]

For Web/API, CSS is marked as an "interface", and we don't have a special page type for namespaces. This is because:

• we call it an interface in our docs, and this page type exercise is mostly about codifying decisions we have already implicitly made
• we would like to keep the number of page types as small as possible, to keep MDN authoring as simple as possible
• it's not obvious to me that MDN readers care about the difference between namespaces and interfaces

I suppose the bottom line is, page types aren't intended to model IDL exactly.

If it's deemed important to make this distinction, we could make a new page type for this special case. But then we also need new page types for the properties and methods that live inside namespaces, since we can't call them "instance methods" and apparently we can't call them "static methods" either. And then we need to update things like the sidebar code, so it can have its own handling for these things. And perhaps all the places our prose refers to them as "static methods" too.

[saschanaz]

I think that's already the case for console functions: https://developer.mozilla.org/en-US/docs/Web/API/console

What works to me is either to:

• Mark all console functions with _static
• Or unmark all CSS functions

... so that we can get some consistency between namespaces.

[wbamberg]

I would be happy to mark console functions static (and update the prose, &c). I suspect we were misled by the lowercase "c" :).

[Elchi3]

I would be happy to mark console functions static (and update the prose, &c). I suspect we were misled by the lowercase "c" :).

I opened #20178 and would welcome thoughts if this is a good idea before I apply the same change to MDN content.

[OnkarRuikar]

For Web/API, CSS is marked as an "interface", and we don't have a special page type for namespaces.

Can we call them web-api-global-object? Or reuse web-api-global-property like we've done it for performance, indexDB, and caches. And keep properties as web-api-instance-property, likewise for methods. Explanation below.

---

A namespace is a definition that declares a global singleton with associated behaviors. [IDL ref]

I think namespaces are documented to convey the structure; they are not types. In JS namespaces are implemented using objects, and CSS and console are those objects:

// consider console.warn() vs static function AbortSignal.abort()
> typeof CSS
'object'
> typeof console
'object'
> typeof AbortSignal
'function'

> typeof Object.getPrototypeOf(CSS)
'object'
> typeof Object.getPrototypeOf(console)
'object'
>  // AbortSignal itself is a class function

The namespaces are global objects not types(like interface) so method on them can't be static: their prototypes is Object object. We don't have to create new page types for properties and methods as they are instance properties and methods.

We need to simply go with option b: Or unmark all CSS functions. Marking these static is technically wrong.

[Elchi3]

Hmm, I'm not sure if it is technically wrong to have statics on namespaces. We already have that in ECMAScript:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect

The page-types are javascript-namespace and the methods are of page-type javascript-static-method.

So maybe having web-api-namespace as a new page-type and for sub pages re-using the existing web-api-static-method page-type could work?