Better source comments/documentation in packages

[JEbertPrime]

Describe the problem

Familiarizing myself with the internal package source code has been frustrating. Some of the more complex functions can be fairly opaque. The JSDoc type declarations are useful, but it seems like a missed opportunity to be using them exclusively as type declarations when we could add more descriptive information. I understand that investing too heavily into internal documentation pre-1.0 might cause some headaches if there are significant changes to the codebase, but I think the benefits probably outweigh that.

Describe the proposed solution

• Add basic descriptions to JSDoc annotations. Short function and parameter descriptions like the ones described on the JSDoc website are probably all this needs.
• [nice to have] Configuration for JSDoc site generation to create some human-readable docs for development purposes.
• Add some instructions for updating the JSDoc descriptions to CONTRIBUTING.md

Alternatives considered

Wait until 1.0 release, when more stability can be expected for the internal packages.

Importance

nice to have

Additional Information

I'm happy to work on this incrementally as I go through the codebase and learn how it all works.

[benmccann]

I'm happy to work on this incrementally as I go through the codebase and learn how it all works.

That would be very much loved by all. It's been a barrier to anyone trying to get involved in the Svelte codebase including some of the maintainers from other parts of the Svelte ecosystem. There's very few people with the knowledge to do add comprehensive docs, but I think if folks can just learn little areas of the codebase and document it once they have a good understanding like you suggested that's probably one of the most realistic ways to improve it.

[JEbertPrime]

Cool! Do you have any preference for how progress should be made on this? My initial thought is to open up directory-specific PRs so changes can be reviewed/approved in small-ish quantities (e.g. 'Documentation update for ./packages/kit/src/runtime/app').

[benmccann]

Oh, I just realized we're in the SvelteKit repo and not Svelte core 😆 I just assumed Svelte core because internal docs are way more of a pain point there...

Doing updates for a particular directory would make sense. I think especially at the beginning for the first one or two I wouldn't do too much so that you can get feedback on the initial PR and make sure it's going in a direction everyone likes

I just took a look though ./packages/kit/src/runtime/app and honestly there doesn't seem to be anything that obviously needs to to be documented there. Maybe I'm just too close to the code to see what might be non-obvious to a newcomer though. I'm not sure if there was something in the directory that might be non-approachable or you just picked a random directory to mention?

[JEbertPrime]

Yeah that was just a random folder. Off the top of my head, I'd say that some code related to building apps, the dev server, and adapters would benefit from more documentation. I think the main benefit of adding more info to the JSDoc annotations would also just to give better completion/function info while debugging, so even for functions that are pretty easy to grok short descriptions would be a boon.

[benmccann]

Yeah, I agree with all that

[JEbertPrime]

I'll open up a PR for some small changes just to hammer out the process and reference this issue