Static vs instance methods on web API pages

[DerekNonGeneric]

What page(s) did you find the problem on?

Include the URL or URLs where you found the problem.

• https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams

Specific page section or heading?

“URLSearchParams”

What is the problem?

Should be .prototype if these are instance methods.

What did you expect to see?

URLSearchParams .prototype instance method

Did you test this? If so, how?

Nope, I have taken the word of @mathiasbynens (he is probably busy atm, so here is the bug report).

[mathiasbynens]

Writing URLSearchParams.append strongly suggests it's a static method (like e.g. Array.isArray), when in reality it's a prototype method:

URLSearchParams.append;
// → undefined
URLSearchParams.prototype.append;
// → ƒ append() { [native code] }

To resolve this confusion, I'd suggest using the URLSearchParams.prototype.append notation for prototype methods. If you need a shorthand, you could consider the # notation i.e. URLSearchParams#append which at least has the benefit of not being valid JavaScript syntax, making it more obvious that a shorthand is being used. But IMHO the best solution is just to use the complete .prototype. notation.

Note that URLSearchParams.prototype.append is just one particular example — MDN uses the wrong notation on many other pages.

[Elchi3]

Thanks for this issue.
Have a look at https://discourse.mozilla.org/t/incorrect-titles-for-method-property-articles/31641 for some more thoughts on this topic :)

[mathiasbynens]

@Elchi3 Thanks for the pointer. What's the current status? The discourse thread hasn't received updates in a few years, and it looks like the originally reported issue is still present (except for the ECMAScript language features, which you’ve carefully titled correctly — thank you!).

[DerekNonGeneric]

Updated the title of this issue.

This page may be a good starting point for how we differentiate instance methods and static methods.

Perhaps dividing the section into two parts (each w/ separate subheading) would make a clear distinction.

[After testing this on Firefox, it appears that none of these methods are static.]

Nevertheless, somehow indicating whether static vs. instance methods seems like a good idea.

[Rumyra]

I've moved this issue into a discussion as originally the thoughts on moving static vs instance methods happened on discourse ^^ and as we've moved mostly to gh, it'd be good to carry it on here...

I was originally going to add highlights from that discussion here, but it's really long - @chrisdavidmills summed it up in this doc here https://docs.google.com/document/d/19ZJbG3tp7CBygsFCj0BeY9CPWCcvnv75GZeTKhGzSlQ/edit#heading=h.kbc6sak698rz

Orig discourse https://discourse.mozilla.org/t/incorrect-titles-for-method-property-articles/31641

This is also intrinsically tied into how we represent syntax sections on web api pages.

[Rumyra]

I've summed up the previous discussion and Chris' doc:

Current format

Generally Web API pages use the interface name with a capital, then the member e.g. BarcodeDetector.detect() - although there is a lack of complaints from web developers, this can be technically confusing as it suggests the method can be called without constructing the interface - ie a static method.

This, by and large, is also used in the syntax section. (See https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector/detect ) and for the same reasons can be confusing.

Now that static members are becoming more popular within Web API interfaces, we should probably decide on a way to represent this site wide.

Options so far:

1. Do nothing - page titles are not supposed to be actual code snippets
   • Pros It's the easiest solution
   • Cons Unhappy people might increase with the rise in static members, SEO could potentially be improved if we did change them(?)
2. Adding .prototype to instance members e.g. BarcodeDetector.prototype.detect()
   • Pros Technically correct
   • Cons Change might affect SEO & possibly affect search, users complain about the use of .prototype in JS pages → confusing, not all accesses to these APIs are done through JS
3. Change the page titles to interfaceInstance.member
   • Pros Technically accurate, low in terms of effort
   • Cons How do we name the instance and keep that consistent. This could also confuse users to see something different from the interface or landing page.
4. Change the page titles to member
   • Pros
   • Cons As previously, the interface name is important to the title of the page
5. Change the page titles to interface#member
   • Pros Used to substitute .prototype, short
   • Cons Not JS syntax, not very common so could confuse users

Other suggestions

• SharedWorkerGlobalScope close()
• SharedWorkerGlobalScope: close()
• SharedWorkerGlobalScope: close() method
• close() method (SharedWorkerGlobalScope)
• SharedWorkerGlobalScope close() method: Terminate a shared worker’s scope
• The SharedWorkerGlobalScope class’s close() method
• close() method (SharedWorkerGlobalScope class member)
• Shared Worker API close() method

Considerations

Interface landing pages should be more explicit about instance/static members. I think we've generally started to use the Static Methods heading.

Member pages should state in the summary if they are static: "The static x method of the y interface"

Should the JS ref pages be consistent with the decided solution?

Another point made in the discourse worth considering is we use the term interface on MDN, which is really class in terms of javascript - I personally don't see an issue with this. We haven't received any communication from developers that this is confusing. Also this term is everywhere and quite a big task to change, for (I believe) not a lot of reward.

Syntax sections

Possibly outside the scope of this title specific discussion, but related. Things I have thought about are the variety within Web APIs:

• Workers/Worklets
• Promise based methods
• Other return types

[DerekNonGeneric]

Change the page titles to interface#member

This seems like a poor choice to me for several reasons. Although being a shorthand for .prototype. that is invalid JS syntax, IMO it's much too obscure of a notation and extremely challenging to search for if trying to find the name of that notation.

[hamishwillee]

@Rumyra Great summary. What would you have/what are options for the title of a Static method then? (or would that depend on the answer for instance methods)?

[mathiasbynens]

Change the page titles to interface#member

This seems like a poor choice to me for several reasons. Although being a shorthand for .prototype. that is invalid JS syntax

IMHO, Foo#bar being invalid JS syntax is better than the status quo of using valid JS syntax Foo.bar that gives the wrong result (e.g. URLSearchParams.append === undefined instead of the function the MDN page describes). That said, I do agree # is probably not the best solution. Any of "Foo.prototype.bar", or "foo.bar" (with lowercase foo to denote it's an instance), or "Foo: bar method" would be much less confusing than the status quo.

[chrisdavidmills]

"foo.bar" (with lowercase foo to denote it's an instance)

From the user research that was done on this quite a while ago, this was seen as the best option. A lot of interviewees noted that they tend to search for something close to the code they'd actually use to access a property/method

[DerekNonGeneric]

The problem with this is that there are web APIs that start with a lowercase letter already (e.g., console), so playing w/ the capitalization here seems like a poor choice as it goes into opinions about variable naming that could violate some code conventions / style guides.

[Rumyra]

I quite like some of the 'Other Suggestions' - I don't think users will search for Interface#member... well not until they get used to it maybe. But it's misleading in regards to how you would use the member in code...

Possibly one of these two:

• SharedWorkerGlobalScope: close()
• SharedWorkerGlobalScope: close() method

It mentions the interface, I like the latter one as we could include 'static method' if it's static. Also it's relatively short compare to a couple of other suggestions. We are still faced with the issue that this isn't how you would write it in code, but I think the colon suggests that you don't.

[DerekNonGeneric]

SharedWorkerGlobalScope: close() method

This might be okay for a page title, but when documenting the API in detail, I would like to see the signatures filled out as we currently have it in our latest PR — Document “AsyncGenerator” & “AsyncGeneratorFunction” #2861. I have not done extensive research on this, but depending on the result of this discussion, we may need to go back to that one and make corrections if necessary.

[Rumyra]

I'm looking to update that PR this week @DerekNonGeneric - I doubt this conversation will influence it as that's Javascript documentation and this is discussing Web APIs

I do agree there's probably a few more points to be made about the content of the member pages in regards to static and not just the title. However if we start with that we can determine best content practices 👍

[jpmedley]

Whatever decision is made should be decided on through the lens of best writing practices. The most relevant one are:

• Use definite, specific, concrete language
• Do not take shortcuts at the cost of clarity

A solution like "SharedWorkerGlobalScope: close() method" definitely follows the first. I think the use of a symbol like "#" violates the second. How do I search for the meaning of that? I've never been crazy about having the word 'prototype' in method titles because I don't use that in actual code. But at least you can look it.

[jpmedley]

I've never liked 'prototype' because its only clear if you're experienced with JS.

[hamishwillee]

I've never liked 'prototype' because its only clear if you're experienced with JS.

I come from a non-JS background and I agree. I prefer the suggested options:

SharedWorkerGlobalScope: close() method
Notification: requestPermission() static method

Devil's advocate - while SharedWorkerGlobalScope.prototype.close() does not scream "instance method", consistency and being technically correct have a value all of their own. By which I mean that if I saw prototype in everything I looked at it would only take a few minutes for me to work out and understand the paradigm going forward.

[Rumyra]

Thanks @hamishwillee soz I wasn't particular above about using that format for static vs instance - but yes I think this seems like a good final suggestion

[Rumyra]

How does everyone feel about this for renaming Web API member pages?

SharedWorkerGlobalScope: close() method
Notification: requestPermission() static method

[mathiasbynens]

Sounds great!

[sideshowbarker]

SharedWorkerGlobalScope: close() method
Notification: requestPermission() static method

I think anything that gets us away from misleadingly using static property and method syntax for instance properties and methods — the way we have been — would be a huge improvement in making the titles and cross-references unambiguous for developers.

And I think the formulation in the proposed resolution does that better than the alternatives.

But to be clear: Does the proposed resolution include adopting that same formulation for properties too? That is, e.g.:

SharedWorkerGlobalScope: name property
Notification: permission static property

Regardless, I have a few more comments about why I think the proposed resolution is good — but they are longish comments (I care a lot about getting resolution on this, so I have a lot to say…) — so I tucked them into the details section below, to avoid having the thread lose focus on the proposed resolution itself in https://github.com/mdn/content/discussions/5121#discussioncomment-785747 just above.

A few more longer comments about why the proposed resolution is good…

One thing @Elchi3 brought up in https://discourse.mozilla.org/t/incorrect-titles-for-method-property-articles/31641/21 about a previously proposed formulation was that it would end up making the sidebars looked more cluttered. The example he gave was of a grouping we currently have in a sidebar like this:

Array.from()
Array.isArray()
Array.of()
Array.prototype.concat()
Array.prototype.copyWithin()

And what at the time had been suggested as a replacement was this:

Array: static from() method
Array: static isArray() method
Array: static of() method
Array: concat() method
Array: copyWithin() method

And I agree that does look cluttered — due to where the word static was placed. But with what’s being proposed as a resolution here, that example grouping in a sidebar would instead look like this:

Array: from() static method
Array: isArray() static method
Array: of() static method
Array: concat() method
Array: copyWithin() method

Specifically, the difference of course is that it moves the static word after the member names rather than squishing it in between the object names and member names.

So I think that objectively looks less cluttered than the previous proposal that had static in front of the member names.

But on top of that, to my eyes at least, it also looks less cluttered than what we are doing now, with having .prototype. for the cases of instance members.

Specifically, it looks better to consistently have member names right after object names — with nothing in between.

And as much as I like the clarity of .prototype. for instance members (as the ES spec uses), I think the formulation in the proposed resolution here shows it’s not necessary — we can achieve the same clarity with less verbosity.

That is, if we say Array: concat() method, that unambiguously means concat() is an instance method — because if it were as static method we would explicitly say, static method.

On other thing I want to point out is: If we were to adopt this proposal for instance members but mix it with continuing to use the least-verbose way to refer to static members — which is to just keeping using, e.g., Array.from() for those, as we’re doing now in the JavaScript docs — then what we’d end up with in sidebars is cases like this:

Array.from() method
Array.isArray() method
Array.of() method
Array: concat() method
Array: copyWithin() method

…which, due to inconsistent alignment, would seem to take us back to a problem of creating cluttered-looking sidebars.

So I think the consistency of instead always having the Array: foo() pattern clearly looks a lot better:

Array: from() static method
Array: isArray() static method
Array: of() static method
Array: concat() method
Array: copyWithin() method

Last word: I know this discussion topic was scoped to getting a resolution on the API docs — and my examples here are from the JavaScript docs — but I think whatever we resolve for the API docs, we should also do for the JavaScript docs.

I say that because it seems best in principle to do the same thing consistently for both doc sets — but I say it also because I think the examples referred to here show that it would work very well for the JavaScript docs too.

[Rumyra]

Ahhhh 🙌 @sideshowbarker your long answer is 😘

So I think in conclusion we should start by changing the Web API docs to the proposal - by and large there's a greater amount here in tier 2 docs (and although I don't think less important) - I do think it'd be good to see if we get any push back - ie any issues because users are confused for a reason we haven't yet foreseen.

I'm going to chuck this up to a priority for myself, but bear with as I'm still going through a bunch of 'Chris leaving™️` admin. I haven't considered how to approach the changes yet, so if anyone wants to give it a go, or has a good idea to grep, pls let me know :)

[hamishwillee]

@Rumyra I like @wbamberg approach - create a parent issue and invite people to join. This will not be my immediate priority though :-)

[hamishwillee]

@sideshowbarker @Rumyra re https://github.com/mdn/content/discussions/5121#discussioncomment-812580

1. We don't need to be constrained by the sidebar having same rendering as page title. We might, for example, use an icon to indicate the static or instance.
2. Following from that, perhaps static or instance are actually frontmatter metadata properties. Then you could have the title field being Array: of() and static or instance get injected as needed for display.

just a thought.

[wbamberg]

While I like these as page titles I think we should have a different approach to sidebar entries. The reason is that sidebars already provide the context that these longer titles give, and repeating the context for every item looks silly and makes them harder to scan:

Date
    Static methods
        Date: now() static method
        Date: parse() static method
    Instance methods
        Date: getDate() method
        Date: getDay() method
        ...

I think it's better to have:

Date
    Static methods
        now()
        parse()
    Instance methods
        getDate()
        getDay()
        ...

...but there are various ways to do this, and that seems like a different problem from page titles.

perhaps static or instance are actually frontmatter metadata properties. Then you could have the title field being Array: of() and static or instance get injected as needed for display.

Yes, that's definitely one option to consider.

[sideshowbarker]

We don't need to be constrained by the sidebar having same rendering as page title. We might, for example, use an icon to indicate the static or instance.

While I like these as page titles I think we should have a different approach to sidebar entries. The reason is that sidebars already provide the context that these longer titles give, and repeating the context for every item looks silly and makes them harder to scan

Understood — but let’s at least please consider not blocking the title changes on needing to have updated sidebar handling in place first. I think it’s more important to get the title changes landed first, and then we can work later on updating the sidebar code and whatever else.

I think we can at least say that per the examples at https://github.com/mdn/content/discussions/5121#discussioncomment-812580, the title formulation in the proposed resolution won’t make the sidebars look worse — though I agree there’s room for improvement to work later on making them less verbose.

[jpmedley]

One thing I should have commented on the other day is the use of the colon. I don't see what it adds to this.

[Rumyra]

In regards to the titles I think it adds a good 'this is not actual code' break between InterfaceName and member - just in case users assume the space either isn't there, or the title is missing a fullstop/period and we're in the same situation we are now (with issues being raised) - this is all just my assumptions however...

[sideshowbarker]

One thing I should have commented on the other day is the use of the colon. I don't see what it adds to this.

Fair question. It makes me realize I have no strong opinion either way about whether we have the colon in there or not.

But that said, there are some reasons the colon makes some sense:

1. The colon disambiguates whether the word preceding is an object name or not — especially in cases where the object is a word than could be an object name but could also just be a normal term; for example:

   • URL: createObjectURL()
   • Array: isArray()
   • Notification: permission

2. The colon explicitly signals a structured association pointing from the object name preceding the colon to the member name which follows the colon. I guess to signal that association, there are other “pointing” symbols we could use which would maybe signal that even more clearly; for example:

   • Array▸ isArray()
   • Array→isArray()
   • Array➝isArray()
   • Array➠isArray()
   • Array➟isArray()
   • Array↠isArray()
   • Array» isArray()

   …but the colon has the big advantage of being much easier to type — it’s some which can typed directly from the keyboard rather than needing to use a symbol picker.

3. Related to #1 above (or maybe just restating it): Without the colon, some combinations of object names and member names read especially awkwardly or unclearly; for example:

   • Array isArray()
   • Notification permission

   Especially for “Notification permission”: Is that referring to the general “Notification permission” concept/feature, or what? Of course if it’s written out as the Notification permission static property, it’s less ambiguous.

   But then if for sidebars we end up doing what’s been discussed in this thread, “Notification permission” would appear just like that in the sidebar — without the static property part. Of course the fact the words will be in monospace as Notification permission will help to disambiguate it — as well, in the sidebars, as any icon/symbol to indicate “static”.

   But to me at least, with no colon or other symbol, it’d look odd, and Notification: permission looks better.

[jpmedley]

I withdraw my object to the colon.

[Rumyra]

I realise this work is yet to start, but I'm might be holding off until web API goes for markdown conversion, just in case I can get this shoe horned in when we tidy up those pages 😬

[jpmedley]

One thing this whole discussion keeps forgetting, it seems to me, is that we're talking about writing not code. There is a best practice that goes "do not take shortcuts at the cost of clarity" (Strunk and White V-19). Specifically, anything that involves a symbol is a shortcut. And if readers have to consult another page to find out what the symbol means, we've failed at the first rule of writing: be clear and direct. (The same applies to the use of prototype in the name.) Why don't we just say what they are?

doStuff() Static Method
doStuff() Instance Method

[beaufortfrancois]

Thank you @Rumyra ;)

[beaufortfrancois]

Do you have any rough ETA when this change will happen?

[Rumyra]

We're currently discussing how we're going to approach this @beaufortfrancois - but I'll update here (sorry for not being more definite)

[wbamberg]

From mdn/content#15525 (comment) : can we apply the change proposed here to the JavaScript documentation as well as the Web/API docs?

[Rumyra]

Yeh - I think so. We can still have a little chat about it in the next editorial I think, just to clarify the approach really 👍

[foolip]

whatwg/fetch#1392 raises the priority of this, since there will soon be both Response.prototype.json and a static Response.json. Neither BCD nor MDN is set up to handle this, since both would have the same paths.

[wbamberg]

I made a spreadsheet that I hope summarises the answer in this discussion, showing what page titles would look like for all the different types of reference pages under Web/API: https://docs.google.com/spreadsheets/d/1AqiTcnQa74Dq-pAJKq1LLo3iple2MN1NoWAAGQlorIA/edit#gid=0.

[domenic]

This proposal looks great to me. This would solve such a huge issue with MDN and I would love to see it implemented.

[wbamberg]

These changes potentially make Web/API page titles localisable, when before they weren't:

BluetoothDevice.name -> BluetoothDevice: name property

...etc. I wonder what @SphinxKnight thinks? If we do want to translate them, perhaps it would be better to construct these titles in Yari, rather than to write them directly into the index.md pages.

[SphinxKnight]

...etc. I wonder what @SphinxKnight thinks? If we do want to translate them, perhaps it would be better to construct these titles in Yari, rather than to write them directly into the index.md pages.

Well, a bunch of pages already have "non keywords" content (Learning Area, but also some HTML elements) and localizing them in the index.md doesn't make much of a difference.

What's more complex is the ordering of words in the presentation and the potential impact it might have on wrapping BaseAudioContext: createdDynamicsCompressor() method would be Méthode createdDynamicsCompressor() de BaseAudioContext or Méthode BaseAudioContext: createDynamicsCompressor() in fr for example (the former is "frenchier" but the latter is more readable).

In the end, it would be up to each locale to find out which form is the best.

[wbamberg]

Oh that's a good point. You'd need proper interpolation, we can't just look up strings in L10Common.json. Is there an existing mechanism for this in Yari? Otherwise I suppose this:

localizing them in the index.md

is the alternative. It just seems a bit broken when you have thousands of titles following the same pattern.

[SphinxKnight]

I'm not aware of such a mechanism in Yari (and tbf I'd prefer to have the UI l10n less broken first :/ mdn/yari#6282).

[sideshowbarker]

See also the related issue at at https://github.com/orgs/mdn/discussions/264, which is specifically about what the URLs for the pages should look like.

[wbamberg]

One of the consequences of the new Web/API page titles is that they will be longer. It's potentially undesirable to have page titles that wrap - or at least if they are going to wrap we would like them to wrap nicely.

Some of our page titles already wrap, and it looks bad:

It looks like page titles will start wrapping at around 37 characters (depending on the characters, of course, because they're not in a fixed-width font). In the table below I've summarised how many pages under Web/API (except guide pages, which we might expect to wrap and which are anyway unaffected by the new titles) would be more than 37 characters under the old and new formats.

	Total	> 37 chars
Old	5695	528
New	5695	1556

So this is showing that out of 5695 pages, about a quarter of the new titles will wrap, compared with less than 1/10 of the old ones.

However! These long titles will usually contain spaces: InterfaceName: methodName() method and we will preferentially wrap at spaces. So the example above would look like this:

...which actually looks all right.

So maybe this is OK?

[Rumyra]

Amazing @wbamberg thanks for doing the screenshots! I think this looks better, but I guess it could also be coincidence it's breaking at a good point. If this was static the proposed 'new way' would drop it to three lines, but I wonder about weighing that up against how many times the title would drop to three lines, because I don't think it would happen too often.

I think if we roll out the changes we can observe feedback as we go(?)

[teoli2003]

Yes, although we should not forget about the effect on the sidebar. It could need a small update to them beforehand (small = 5-6 lines max) (If we use titles to get the name, none if we use the slugs)

[wbamberg]

If this was static the proposed 'new way' would drop it to three lines, but I wonder about weighing that up against how many times the title would drop to three lines, because I don't think it would happen too often.

This is what titles would look like for all 37 of the pages that have a web-api-static-property or web-api-static-method page type:

AbortSignal: abort() static method
AbortSignal: timeout() static method
BarcodeDetector: getSupportedFormats() static method
CSS: escape() static method
CSS numeric factory functions static method              <- this one is weird
CSS: paintWorklet static property
CSS: registerProperty() static method
CSS: supports() static method
CSSNumericValue: parse() static method
DOMPoint: fromPoint() static method
DOMPointReadOnly: fromPoint() static method
DOMRect: fromRect() static method
DOMRectReadOnly: fromRect() static method
HTMLScriptElement: supports() static method
IDBKeyRange: bound() static method
IDBKeyRange: lowerBound() static method
IDBKeyRange: only() static method
IDBKeyRange: upperBound() static method
ImageDecoder: isTypeSupported() static method
MediaRecorder: isTypeSupported() static method
MediaSource: isTypeSupported() static method
MouseEvent: WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN static property
MouseEvent: WEBKIT_FORCE_AT_MOUSE_DOWN static property
Notification: maxActions static property
Notification: permission static property
Notification: requestPermission() static method
PerformanceObserver: supportedEntryTypes static property
PublicKeyCredential: isUserVerifyingPlatformAuthenticatorAvailable() static method
Response: error() static method
Response: redirect() static method
RTCPeerConnection: generateCertificate() static method
RTCRtpReceiver: getCapabilities() static method
RTCRtpSender: getCapabilities() static method
URL: createObjectURL() static method
URL: revokeObjectURL() static method
VideoEncoder: isConfigSupported() static method
XRWebGLLayer: getNativeFramebufferScaleFactor() static method

I reckon maybe 7 of them would go to three lines, and one of them already does.

I guess it could also be coincidence it's breaking at a good point.

It's not really a coincidence. Breaking at spaces is always better than breaking in the middle of a word, and we're adding more spaces, so we're increasing the chance that there will be a sensible place to break.

[wbamberg]

Yes, although we should not forget about the effect on the sidebar. It could need a small update to them beforehand (small = 5-6 lines max) (If we use titles to get the name, none if we use the slugs)

This is what short-title is for, or am I misunderstanding you?

[caugner]

My concern with the discussed solution is that making the page title itself more verbose increases the time it takes to read/understand it (i.e. you have to "look twice" to understand what page you're looking at), so I will throw in an alternative solution that communicates the method type (~page type) via a badge, and - for very long method names - breaks between word parts rather than within a word part:

Before:

Keeping the dot:

Replacing it with a colon:

And just as an experiment, I have highlighted the method name to make it easier to distinguish the interface and method:

[wbamberg]

A related issue came up yesterday: mdn/content#21960 (comment). The page wanted to link to https://developer.mozilla.org/en-US/docs/Web/API/Navigation/updateCurrentEntry, but the link text was just updateCurrentEntry(). I think it's helpful to include the interface here, but the way we usually do that is Navigation.updateCurrentEntry(), which has the same issue as we do for titles.

In this case we can't really have "Navigation: updateCurrentEntry() instance method". Perhaps it would be OK to have Navigation/updateCurrentEntry() or Navigation#updateCurrentEntry()? We can probably do this in the domxref macro.

[DerekNonGeneric]

Navigation#updateCurrentEntry()?

-1 on the #

[saschanaz]

Yeah, # can be confusing given that we have .# private member accessor.

[domenic]

I've always preferred navigation.updateCurrentEntry(), since that's what a web developer would actually type...

Another option is "Navigation's updateCurrentEntry()".

updateCurrentEntry() is way better than Navigation.updateCurrentEntry() though. The latter is just actively misleading and harmful.

[wbamberg]

A few weeks ago I filed a draft PR to show what some page titles would look like based in the proposal at https://github.com/orgs/mdn/discussions/248#discussioncomment-3797416. Now people have had a chance to look, this comment summarises where we are with this project and what's next.

1. we're overall happy with the page titles as described in https://github.com/orgs/mdn/discussions/248#discussioncomment-3797416 and demonstrated in the draft PR: Web API titles: some sample interfaces content#21810. One question that's emerged is Web API titles: some sample interfaces content#21810 (comment) - whether we should have a different title form for constructors. I'm not in favour of this (for consistency) but don't feel too strongly.
2. we will add short-title at the same time, so sidebars look good still. We have a branch of Yari for the APIRef macro to use short-title: https://github.com/wbamberg/yari/tree/apiref-short-title and that can be merged without needing the short titles (i.e. we can merge it now, and it will only do anything for pages that actually have short titles)
3. for localizers: these titles will be localized content. When and if Yari supports localization we might want to revisit that: https://github.com/orgs/mdn/discussions/248#discussioncomment-3923476.

So I think if we can agree about the constructor question we can go ahead?

If so, the plan is:

1. make the Yari short-title change into a PR and get it merged
2. update titles for a couple of hundred pages, to check the scripts work
3. update PRs for all the other pages.

This plan does not yet enable us to have separate pages for static and instance methods with the same name. It's necessary but not sufficient, because we also need updated URLs for that. For URLs, I think the plan is to have a _static suffix for all static methods and properties. We would need to consider what to do about domxref.

[Rumyra]

Thanks so much for this @wbamberg

[wbamberg]

@Rumyra , does this mean I can start work on this, or is there some more discussion needed?

[Rumyra]

No but I do have a process I'd luv to practise for this - I'll message 👍

[wbamberg]

It's back! See mdn/content#30238 (comment) not to mention https://github.com/orgs/mdn/discussions/248#discussioncomment-4102050 from this thread.

We fixed this for page titles but not for in-prose link text. Perhaps we ought to go for interfaceName.methodName() for instance methods, here, as Domenic suggests in https://github.com/orgs/mdn/discussions/248#discussioncomment-4102782?

We could do this in domxref.

[hamishwillee]

@wbamberg So who can make that change? ("what is the best way in your opinion to make this happen")?

The macro will also find the right interface if you do {{domxref("Performance.now()")}} (or I believe {{domxref("Performance.now")}} ) . We should make sure it can also do the right thing with the lower cased variants (such as {{domxref("performance.now()")}} ) as part of this.

I don't think that we will be able to avoid talking about the linter, or at least fixing up a bunch of non-macro links, because this change will make things inconsistent. However that can be a problem for another day.

IF we do this we should update the style guide either way.

[wbamberg]

@wbamberg So who can make that change? ("what is the best way in your opinion to make this happen")?

File a Yari bug?

The macro will also find the right interface if you do {{domxref("Performance.now()")}} (or I believe {{domxref("Performance.now")}} ) . We should make sure it can also do the right thing with the lower cased variants (such as {{domxref("performance.now()")}} ) as part of this.

Yes. Seems like it does this already: https://github.com/mdn/yari/blob/35a3bf8b31955e067e148d836fb4c59d29db7c00/kumascript/macros/DOMxRef.ejs#L35 ?

I don't think that we will be able to avoid talking about the linter, or at least fixing up a bunch of non-macro links, because this change will make things inconsistent. However that can be a problem for another day.

When we talk about linting though are we just talking about linting link text or all text? Because it's a bit hard for me to see how a linter could find non-link text reliably, but unless it does things will still be inconsistent: not all references to performance.now() are linked. It would be interesting to know how many non-domxref links to reference pages we have at the moment.

IF we do this we should update the style guide either way.

Sure.

[OnkarRuikar]

Doing this only in the macro will not completely solve the issue the inline code will remain. People will still raise issues, saying, "You keep switching the capitalization!".

A linter will be able to catch `Performance.now()` and [`Performance.now()`](/en-US...) cases easily. And I hope people don't write Performance.now() without backticks. The linter has the ability to avoid looking in the code fences and process only the prose; the search-replace plugin is doing it already.

How much do we want to involve the contributors in this? a) They won't know till the PR companion shows the flaws, and like the other fixable flaws, we auto-fix this every midnight behind-the-scenes. b) We outright prevent them from making a local git commit.

[hamishwillee]

I agree that this doesn't fix the problem unless we fix it all the way. But it can be done in bits. My preference is auto fixing almost every case behind the scenes. Blocking on local git commit is a pain in the bum.

[OnkarRuikar]

Very well then, we need to file a bug in rari to update the domxref macro to mark lowercase instance references as flaws and make these flaws autofixable.