maybe improve types documentation a bit

[Rich-Harris]

Deployed here: https://kit-svelte-dev-git-better-docs-svelte.vercel.app/docs/types-presentation

Some of the documentation around types is a bit ropey. For example I don't love how this looks:

Also, the configuration documentation is kind of all over the place — this stuff really belongs in types/index.d.ts, so that it appears inline when you're actually writing the config, rather than being manually written in a separate documentation file where it's less useful (and manually maintained as we make changes).

In this PR I'm trying some ideas for how we might improve it a bit. Am open to all suggestions. Some of this might need custom CSS to make it look halfway decent.

[changeset-bot]

🦋 Changeset detected

Latest commit: 0ed36e1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
create-svelte	Patch
@sveltejs/kit	Patch

Not sure what this means? Click here to learn what changesets are.

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

[SrGeneroso]

Just learning TypeDoc while learning TS.
My main motivation to learn TS is in fact having docs for free*. This combo is making me fall in love with TS. I heard JsDocs was gaining some traction in the svelte community as the first step to TS without having to get married to it.
Should svelte/kit have both? It seems JsDoc and TsDoc is mostly interoperable (don't have to add the type in the params in TsDoc as one diference), don't know enough to comment on it, but I've seen some TypeDoc magic that I can't wait to see around here. I might be talking nonsense and all of this is already implemented or something else, I just wanted to bump this, I'd loved to see better documentation not only for final users but also for devs of svelte/kit.

EDIT: is this hilarious?

[dummdidumm]

Some general thoughts aside from the inline comment:

• the "generated types" and "tsconfig" sections are related, but they feel a little lost down there on that big API reference page. It feels like they deserve its own section
• speaking of API reference: Maybe it should be named that instead. Yes it's types, but they at the same time represent the API of these things, moreso if we transform them to something more appealing like this. So maybe "generated types" and "tsconfig" stay where they are and the rest moves to a new API section
• for inspiration, this is how the API section of the Angular docs looks like: https://angular.io/api . They have an overview and then separate pages for each. Depending on how elaborate we become with all these types this may or may not make sense. Too many little pages scattered out feels wrong, one giant page also feels wrong, something inbetween would be nice

[dummdidumm]

During the work on #7087 I felt hindered by having to write more detailed docs inside JSDoc. You can't use JSDoc within JSDoc for example (/** @type {..} */ will close the outer JSDoc). Moreover, it could get overwhelming seing an ocean of docs when hovering over a function. In also complicates future enhancements like translation or JS+TS in the docs with a switch.

I therefore think we need a different approach - some kind of mix between manual docs and "include X from the types". Made-up example-MD file that would need to be preprocessed:

## cookies

### set

--definition-- // <- this would extract the type definition from types.d.ts into here
--summary-- // <- this would extract the JSDoc from types.d.ts into here in case you don't want to duplicate things

Lorem ipsum bla whatever you need additionally

[dummdidumm]

Reverting part of my previous comment - the API docs should be very concise and more on the short side. The cookie example is the biggest it should probably get. If there's more it should go into a different part of the docs, explaining things in more detail and in the context of usage. What remains is the question about code samples, which I don't have a good answer to. Edit: Seems like there's an example of this in the ambient type definitions already. It's writtin in a way that doesn't break the JSDoc but the docs are borked if you hover over them from your IDE. not sure what's the best solution here.

[dummdidumm]

I pushed a POC of a generator enhancement that transforms interfaces into better looking docs similar to what you proposed. I added a border to each of the snippets that present sub headline to better distinguish them from regular code snippets. I also kept a trimmed down version of the whole interface at the start of each section so people can get a quick overview of that type.

I think the result is much better-looking, but only if we have actually some docs in there - so I think if we change this, we should also get down to writing a lot more quick API docs here at the same time.

The final part of the picture (for me at least) would be to restructure the types and modules sections into one "API Reference" section, and we group the modules / interfaces logically into sub pages. Does this make sense? (Related: I think refining the side bar would be good; only showing the headers, not the sub headlines).

[dummdidumm]

No idea why this fails ... I need to investigate more thoroughly tomorrow. So far it looks like this only fails for .svelte files, so this might be some bug inside language tools.

[dummdidumm]

"maybe", "a bit" - turned out to be far more than that 😄

[dummdidumm]

No idea why this fails ... I need to investigate more thoroughly tomorrow. So far it looks like this only fails for .svelte files, so this might be some bug inside language tools.

I lied, this also happens inside TS files. Still no idea why.
Update: I think it happens if the imported type is a function interface (or type) - looks like a bug inside TypeScript. It only happens if you have an ambient file which you export from the main types (so they are available to all), while at the same time importing a function type or interface from those types into one of the ambient modules.

[realvasko]

I was trying to configure the trailingSlash option, as introduced in #733, but found it's missing in the current config and found this to be the PR where it got removed. I couldn't really figure out why, so was wondering if it was intentional? If so, is the feature no longer supported?

[realvasko]

Never mind, saw that it's now part of the page options.