Different slugs for static methods/properties

[wbamberg]

This is part of openwebdocs/project#104, which asks for MDN to be able to document static methods and properties that have the same name as a non-static method/property. This is now a reality with things like Response.json(): mdn/content#21550.

As part of this we need distinct slugs for static and non-static members.

The easiest option is probably adding a _static suffix to the approx 37 pages on MDN that document static methods or properties.

A maybe better but much harder alternative would be to have a structure like:

Response/
   Instance_methods
        /json
   Static_methods
        /json

...but this would involve ~5000 redirects.

Either option (and probably all options) would break various macros and things that expect slugs to be a certain way. But this probably wouldn't be too bad.

[teoli2003]

Either option (and probably all options) would break various macros and things that expect slugs to be a certain way. But this probably wouldn't be too bad.

Whatever option is chosen, we should start by updating macros and things using slugs to derivate page types to use page types instead.

Then, this will be a decision only about the best slug.

[sideshowbarker]

I agree with the suggestion over in mdn/browser-compat-data#16613 (comment) that we add .prototype. to the slugs for all the instance methods — as is done in the all the existing JavaScript docs.

But since adding .prototype. to the slugs for all the instance methods isn’t even mentioned in this issue as a possibility to consider, I guess we’ve ruled it out for some reason? If so, I can’t find a statement anywhere about why.

But if adding .prototype. to the slugs for all the instance methods has already somehow been ruled out, than it seems like in the mdn/browser-compat-data#16613 discussion at least there is some rough consensus already on appending _static to the static methods.

So if we’re not going to do the .prototype. naming, then guess appending _static to the 37 or so static methods that we have documented seems to me like the least objectionable among the other possible options.

[teoli2003]

There may have been a discussion about prototype in titles (I wasn't part of it, so I don't know for sure). I don't think there has been a discussion about adding it to slugs.

If I understand you correctly, you are proposing:

Response/
   prototype/
        /json
   /json

Am I right?

[wbamberg]

I agree with the suggestion over in mdn/browser-compat-data#16613 (comment) that we add .prototype. to the slugs for all the instance methods — as is done in the all the existing JavaScript docs.

But since adding .prototype. to the slugs for all the instance methods isn’t even mentioned in this issue as a possibility to consider, I guess we’ve ruled it out for some reason? If so, I can’t find a statement anywhere about why.

Nope. I'm happy for us to consider this too, and think consistency with JS practice is generally a good thing.

I don't really know how to weigh the cost of thousands of redirects.

[sideshowbarker]

Yes, to be clear I mean this:

URL	method type
https://developer.mozilla.org/en-US/docs/Web/API/Response/json	static method
https://developer.mozilla.org/en-US/docs/Web/API/Response/prototype/json	instance method

…but it’s not something I’m going to lie down in the road about. I recognize that it’d mean changing/redirecting the URLs for all the thousands of existing instance methods, and I can understand why others might not want to do that — and would prefer instead:

URL	method type
https://developer.mozilla.org/en-US/docs/Web/API/Response/json_static	static method
https://developer.mozilla.org/en-US/docs/Web/API/Response/json	instance method

…because that’d mean the URLs for all the instance methods stay as they are now, and we instead change only three dozen or so URLs for the static methods — to have _static appended to their URLs.

[mathiasbynens]

I also prefer the first option. IMHO the number of redirects required is a one-time implementation detail that shouldn't influence our decision.

[foolip]

I'm partial to including prototype as well, but keep in mind that some proprieties aren't on the prototype but only on instances. Web IDL [Unforgeable] has this effect.

[silverwind]

/prototype/ is my clear favorite because it results in the JS name when replacing / with .. Some pages already use it as title.

So I would strongly recommend using /prototype/ instead of _static which seems like a ugly hack to me.

[Josh-Cena]

FWIW the slugs are already long enough and I don't want it to grow longer in any way. Static and instance methods with the same name are unfortunate but they are very rare. IMO these special cases can be handled individually—for example, json_static doesn't sound like a too bad idea.

There's only one such instance in JS—TypedArray.BYTES_PER_ELEMENT is both static and instance, and we are currently missing the former. I do not plan to make a new page (and I already have a branch prepared in my fork to address mdn/content#20019, which is currently blocked by mdn/content#20025); I will just conflate them into one page.

[sideshowbarker]

There's only one such instance in JS—TypedArray.BYTES_PER_ELEMENT is both static and instance, and we are currently missing the former. I do not plan to make a new page (and I already have a branch prepared in my fork to address mdn/content#20019, which is currently blocked by mdn/content#20025); I will just conflate them into one page.

I think for that particular case, putting them on one page makes perfect sense. Or really in general — if we have any similar cases with the Web API docs, or if/when we ever did run into such cases, it would make sense to have one page.

[sideshowbarker]

FWIW the slugs are already long enough and I don't want it to grow longer in any way. Static and instance methods with the same name are unfortunate but they are very rare. IMO these special cases can be handled individually—for example, json_static doesn't sound like a too bad idea.

So far it seems like nobody has said they’d outright strongly object to a _static suffix as the solution. Several of us have said we’d prefer adding /prototype/ to the slugs but nobody’s said it’s a showstopper for them. It’s certainly not for me.

The one thing that’s really important here is that we just find a way to really make this happen this quarter — whatever it takes. Because we have kept pushing this to the back burner for way too long now — literally, for years.

So I wouldn’t want this to get delayed any further over haggling to get resolution on any details that we don’t have very strong disagreements about. And so if a _static suffix as a solution for the URLs is a thing that we can get more agreement for — and getting that agreement helps keeps more urgency and momentum going on this — then we should decide on that and move on to doing all the actual work needed.