docs: update store documentation

[Rich-Harris]

It doesn't really make sense to have a whole load of documentation on svelte/store on /docs/svelte/stores page and then again on /docs/svelte/svelte-store. The first should describe the store contract at a high level, while the second should detail the things you can import from the module.

This is draft because we really need to fix the way overloads are handled first — it's too confusing at the moment

[changeset-bot]

⚠️ No Changeset found

Latest commit: e62a807

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

[pkg-pr-new]

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

commit: e62a807

[dummdidumm]

while I agree in general, I don't want the solution to be stuffing a whole bunch of content into JSDoc. We had this dilemma elsewhere, I think it's time to enhance the auto-generation from d.ts - you should be able to declare additional documentation (or documentation that is used in place of the jsdoc comment) in some markdown file and the generation script stitches them together accordingly.

[Rich-Harris]

stuffing a whole bunch of content into JSDoc

Is the concern that it's annoying to do so (which is true!) or that you don't want that documentation to be present when people hover over stuff in their editor? Because I can't really think of a situation where I wouldn't want the comprehensive documentation to be at my fingertips

[dummdidumm]

• it's annoying
• it's similar to having many things on one page: you feel obligated to be on the short side, and so you might be too brief
• if I hover over a function and get a giant hover box I'm put off (which in turn means I personally feel even more obligated to be brief)

[Ocean-OS]

Is the concern that it's annoying to do so (which is true!) or that you don't want that documentation to be present when people hover over stuff in their editor? Because I can't really think of a situation where I wouldn't want the comprehensive documentation to be at my fingertips

I agree with this, while the JSDoc definitions may seem a little long, they're extremely useful. Svelte isn't that hard to understand, but it's good to get a refresher of how to use certain features if you're new or a little rusty (and don't want to have to dig through documentation to find info)