Documentation should encourage people to use cleanupSome only when appropriate

[tjcrowder]

The explainer doesn't mention cleanupSome at all other than in the "historical documents" section, to point out the motivation for it (long-running Wasm jobs).

Is there any valid use case for it outside of Wasm?

I suppose in a long-running JavaScript job, if you have reason to think there may be a number of objects you haven't had a finalizer call for that you also know you haven't referenced during the job AND you want to do finalization for them, but...sounds fairly dodgy.

Basically I'm wondering if we should be telling people, effectively, "Don't use it, it's for Wasm." :-) (If so, it's probably worth adding a note in the spec -- happy to do a PR if that's the case.)

Thanks!

[littledan]

I agree that we should encourage people to typically depend on the callback that they pass in to FinalizerRegistry, rather than calling cleanupSome. I think the explainer and API shape already encourage that (by taking the callback as a parameter, and by the examples all passing that parameter). I'm not really comfortable making a statement like "it's for Wasm", since I don't think we could really rule out the "long tasks" in a Worker implemented in JS case, from the historical documents. Let's think about how to word this as we write more reference documentation for cleanupSome.

[tjcrowder]

This is handled by the updates to documentation a few weeks back.