Remove Constrain{Double, Boolean, DOMString, ULong} and {ULong, Double}Range

[teoli2003]

In mdn/browser-compat-data#11000, @vinyldarkscratch is planning to remove the bcd entries for these 4 typedefs.

This is a good thing™.

But there are timely consequences for MDN content: these four pages will immediately (when yari pick up the new bcd npm package) replace their BCD and spec tables by error messages, which will make them look weird.

I think we should wipe them out of MDN content by replacing every mentions of these typedef (most of the time by using the js type they are typedefing). That way, the MDN users will have the type information they will see in their developer tools and their JavaScript.

With a few ripgrep magic, I see the following tasks to be done:

1. Removal of ConstrainDouble:

• Delete the ConstrainDouble page (make it a redirect?)
• Update mentions in MediaTrackConstraints, MediaTrackConstraints.volume, MediaTrackConstraints.frameRate, MediaTrackConstraints.latency, and MediaTrackConstraints.aspectRatio.
• Update mentions in InputDeviceInfo.getCapabilities.

2. Removal of ConstrainDOMString:

• Delete the ConstrainDOMString page (make it a redirect?)
• Update mentions in MediaTrackConstraints, MediaTrackConstraints.deviceId, MediaTrackConstraints.displaySurface, MediaTrackConstraints.logicalSurface, MediaTrackConstraints.groupId, MediaTrackConstraints.cursor, and MediaTrackConstraints.facingMode.
• Update mentions in InputDeviceInfo.getCapabilities.
• Update mentions in Screen Capture API overview page.

3. Removal of ConstrainBoolean:

• Delete the ConstrainBoolean page (make it a redirect?)
• Update mentions in MediaTrackConstraints, MediaTrackConstraints.autoGainControl, MediaTrackConstraints.logicalSurface, MediaTrackConstraints.noiseSuppression, and MediaTrackConstraints.echoCancellation.
• Update mentions in InputDeviceInfo.getCapabilities.

4. Removal of DoubleRange:

• Delete the DoubleRange page (make it a redirect?)

I would add an extra step to prevent them to come back to haunt us in the future:

5. Add a new taboo-typedef linter rule forbidding mentions of ConstrainDouble, ConstrainDOMString, ConstrainBoolean, DoubleRange words (and maybe other similar typedef that weren't used yet).

[queengooborg]

Thanks for opening this issue! @saschanaz also has a PR to remove ConstrainULong and ULongRange as well (see mdn/browser-compat-data#10623), so we should account for them as well.

[hamishwillee]

There is a discussion on this here https://github.com/mdn/content/discussions/5828

I'm not sure if there is a canonical result from that, but the implication for me was that it is generally OK to delete separate page documentation for dictionaries and that they should be documented in-place instead.

[teoli2003]

Thanks for the info!

So:
6. Removal of ConstrainULong:

• Delete the ConstrainULong page (make it a redirect?)
• Update mentions in MediaTrackConstraints, MediaTrackConstraints.sampleRate, MediaTrackConstraints.channelCount, MediaTrackConstraints.width, MediaTrackConstraints.sampleSize, and MediaTrackConstraints.height.
• Update mentions in InputDeviceInfo.getCapabilities.

7. Removal of ULongRange:

• Delete the ULongRange page (make it a redirect?)

[teoli2003]

There is a discussion on this here #5828

I'm not sure if there is a canonical result from that, but the implication for me was that it is generally OK to delete separate page documentation for dictionaries and that they should be documented in-place instead.

Yes, at least for dictionaries used in one place (which is most, but not all, of them).

[hamishwillee]

That was my take-away. I've cross linked back to here in the hope that you can get more expert confirmation than I can provide :-). Also, thanks to you and @vinyldarkscratch for letting us know in advance.

[queengooborg]

To go along with my PR for BCD, I'd love to tackle this one! I've got a couple of questions before beginning, however:

• Should we define these constraint typedefs in the MediaTrackConstraints page? These typedefs do include dictionaries with exact (required) and ideal (recommended) parameters for the constraint, and I feel it would be wrong not to document them in some way.
• Where should we redirect the deleted pages to? (If the above question's answer is "yes", I think that pretty much answers this one.)

[hamishwillee]

@vinyldarkscratch Probably :-) Hard to say without trying it.

But yes, I think that is probably your best bet for minimising the amount of duplication and work. So I'd try to pull the definition of exact and ideal into that top level under deviceId and reference up to it from the mention in groupId. Same pattern for the others.

But of course it isn't that simple. What should you do in the property pages like https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/deviceId ? My thinking is that you'd TRY to link up to the the MediaTrackConstraints doc. However for usability you might decide that you'd be best off duplicating the format for the dictionary here too, and also in groupID. [That is what I think I'd end up doing]

Yes, you redirect all of these to MediaTrackConstraints.

Probably there will be some discussion once you have a PR. Sorry I can't be "canonical".

[queengooborg]

Thank you very much, this is a big help! I'm going to give a shot a PR for one of these typedefs and should have it up within the hour!

[queengooborg]

Ooh, actually, I just noticed that at the top of the page, there's a blurb that might just solve the issue altogether:

To learn more about how constraints work, see Capabilities, constraints, and settings.

The linked page seems to describe the constraint typedefs pretty well, documenting the exact and ideal properties. Perhaps we simply link and redirect to that page, considering the detail within the page?

[hamishwillee]

Generally I see guide and reference as separate - so even though this is a good explanation I wouldn't use it as the place where I send people to find out what the dictionaries are. Others might feel differently.

[foolip]

Definitely agree this is a good thing to clean up!

Constraints have a very regular structure allowing both a "naked" value and as well as exact and ideal, so linking to an explanation of that structure in any documentation for methods taking constraint dictionaries seems important. https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API/Constraints is a great page, but it doesn't directly and succinctly explain what the possible shapes of these constraint objects are, although it comes through in examples.

Is there any precedent we can follow here? I was looking for how we document callback functions as arguments, but setTimeout just links to Function, so no inspiration to find there.

[queengooborg]

I've opened #6047 as a proof-of-concept to get an idea for the removal. I'd love to get some feedback on it!