docs: improve createSubscriber documentation

[braden-w]

This pull request significantly enhances the documentation for the createSubscriber function, a crucial but under-documented part of Svelte 5's reactivity system. Key improvements include:

1. Clearer Opening Description: Rewritten in natural language to immediately explain createSubscriber as a "bridge" between external events and Svelte's reactivity.

2. Comprehensive Examples: Added three detailed examples demonstrating common patterns: a generic reactive utility, a class-based MediaQuery integration, and a function-based mousePosition tracker. These highlight proper Svelte 5 patterns and essential cleanup.

3. Improved JSDoc Structure: Enhanced with clear @param tags, multiple @example sections, a dedicated "Implementation Details" section, and a practical "When to use" guide.

This enhancement makes createSubscriber more intuitive and helps developers confidently integrate external APIs, ensuring proper usage to prevent issues such as memory leaks. Hopefully, we can further clarify one of Svelte 5's powerful features!

[changeset-bot]

⚠️ No Changeset found

Latest commit: 15fea4c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-svelte-16310-svelte.vercel.app/

[Ocean-OS]

This looks nice, but seems like too much text for a JSDoc description. Could you move some of it to the documentation?

[github-actions]

Playground

pnpm add https://pkg.pr.new/svelte@16310

[Rich-Harris]

Thank you but I'm afraid I'm going to veto this. It's waaaaay too much text, and is quite repetitive. The examples are also slightly misleading — in the general case it's not enough to have an initial value that is updated in the update callback, because that will result in the surrounding getter returning stale data in the case that it's called outside of an effect (the existing MediaQuery example explicitly calls this out).

There are some good callouts though, which I've worked into a new PR — #16398.

Forgive me if this is incorrect but the PR and its description have a very strong ChatGPT flavour (verbosity, bullet-point lists with three items etc). If that's the case please avoid using it in future PRs!

[braden-w]

@Rich-Harris thank you for the response! And sounds good, will be following #16398 in the future.

in the general case it's not enough to have an initial value that is updated in the update callback, because that will result in the surrounding getter returning stale data in the case that it's called outside of an effect

Thank you for the correction! This is really helpful for improving my own understanding.

Forgive me for the mistakes; it seems like I had somehow accidentally overwrote an old PR I had made about function bindings with this PR (so the title doesn't match, and the description was incomplete). You are also correct; I thought my original PR body (1-2 sentences) was too short for an open-source repository, so I had AI draft a summary of changes in bullet points. I will avoid this in the future; maintainers can simply look at the code tab for more information.

As for the jsdocs, I spent a long time iterating on them because I agree: they look way too verbose. I struggled to find the right balance of being thorough while not overwhelming the reader with information. That being said, it took me a long time to wrap my head on how to use createSubscriber, in part because the documentation on it was relatively sparse. I would love to see the docs improve for newcomers!