Guideline for entrypoints that are too long to spell out

[foolip]

In #1363 (comment) @captainbrosset wrote:

We usually try to name the entry point of the feature in the description. In this case it would be ServiceWorkerRegistration.sync. Although it's a bit long, and devs don't actually write ServiceWorkerRegistration in their code, but instead get a registration object by doing await navigator.serviceWorker.ready. So I'm not too sure what to do here.

I don't think we've dealt with this before, but it will happen quite a lot. This would be terrible:

The (await navigator.serviceWorker.ready).sync API ...

Because it's extremely unlikely anyone would write the code like that.

This specific case is complicated by the fact that there are many ways to get a ServiceWorkerRegistration instance, see the backreferences from https://w3c.github.io/ServiceWorker/#get-the-service-worker-registration-object

Another case is properties on methods on elements. Some precedent from that:

The showPicker() method for <input> elements shows the user interface for picking a value. For example, for <input type="date"> it shows the interface for picking a date.

The preservesPitch property for <audio> or <video> adjusts the pitch of audio to sound more natural when the playback rate is faster or slower than the default.

What should a guideline say?

[ddbeck]

I think the principle is something like this:

To aid search, include literal text that a web developer would inevitably type if they were to invoke the feature. If there's no essential entry point to the feature, then include only concise snippets of essential literal code instead. Never use made-up or idiosyncratic example code.

• 👍 Recommended: display: flex, fetch(), etc.
• 👎 Not recommended: exampleButton.addEventLIstener("newevent", /* … */)

[foolip]

@ddbeck that sounds good to me, and I don't think we have anything like exampleButton.addEventListener("newevent", /* … */) yet. We don't seem to even have cases like video.someMethod() where video stands in for a <video> element instance.

[ddbeck]

Yeah, I should probably have just used your example: (await navigator.serviceWorker.ready).sync

@captainbrosset do you want to offer a take on #1388 (comment) before I open a PR?

[captainbrosset]

Your proposal sounds good to me. Feel free to open up a PR.