[docs] improve documentation for new developers

CONTRIBUTING.md

@@ -26,7 +26,8 @@ Entry points to be aware of are:
 - [`packages/create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte) - code that's run when you create a new project with `npm init svelte`
 - [`packages/kit/src/packaging`](https://github.com/sveltejs/kit/tree/master/packages/kit/src/packaging) - for the `svelte-kit package` command
 - [`packages/kit/src/core/dev/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/dev/index.js) - for the dev-mode server
-- [`packages/kit/src/core/build/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/build/index.js) - for the production server
+- [`packages/kit/src/core/build/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/build/index.js) - for the production build
+- [`packages/kit/src/core/sync/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/sync/sync.js) - for `svelte-kit sync`, which regenerates routing info and type definitions
 - [`packages/adapter-[platform]`](https://github.com/sveltejs/kit/tree/master/packages) - for the various SvelteKit-provided adapters
 
 Most code called at build-time or from the CLI entry point lives in [packages/kit/src/core](https://github.com/sveltejs/kit/tree/master/packages/kit/src/core). Code that runs for rendering and routing lives in [packages/kit/src/runtime](https://github.com/sveltejs/kit/tree/master/packages/kit/src/runtime). Most changes to SvelteKit itself would involve code in these two directories.

packages/kit/src/core/adapt/builder.js

@@ -2,6 +2,7 @@ import { copy, rimraf, mkdirp } from '../../utils/filesystem.js';
 import { generate_manifest } from '../generate_manifest/index.js';
 
 /**
+ * Creates the Builder which is passed to adapters for building the application.
  * @param {{
  *   config: import('types').ValidatedConfig;
  *   build_data: import('types').BuildData;

packages/kit/src/core/build/utils.js

@@ -8,7 +8,10 @@ import { get_aliases } from '../utils.js';
  * @typedef {import('rollup').OutputAsset} OutputAsset
  */
 
-/** @param {import('vite').UserConfig} config */
+/**
+ * Invokes Vite.
+ * @param {import('vite').UserConfig} config
+ */
 export async function create_build(config) {
 	const { output } = /** @type {RollupOutput} */ (await vite.build(config));
 
@@ -24,6 +27,7 @@ export async function create_build(config) {
 }
 
 /**
+ * Adds the transitive JS and CSS to the js and css inputs.
  * @param {string} file
  * @param {import('vite').Manifest} manifest
  * @param {Set<string>} css
@@ -45,6 +49,7 @@ export function find_deps(file, manifest, js, css) {
 }
 
 /**
+ * The Vite configuration that we use by default.
  * @param {{
  *   client_out_dir?: string;
  *   config: import('types').ValidatedConfig;

packages/kit/src/core/config/index.js

@@ -5,6 +5,8 @@ import { logger } from '../utils.js';
 import options from './options.js';
 
 /**
+ * Loads the template (app.html by default) and validates that it has the
+ * required content.
  * @param {string} cwd
  * @param {import('types').ValidatedConfig} config
  */
@@ -36,6 +38,11 @@ export function load_template(cwd, config) {
 	return fs.readFileSync(template, 'utf-8');
 }
 
+/**
+ * Loads and validates the svelte.config.js
+ * @param {{ cwd?: string }} options
+ * @returns {Promise<import('types').ValidatedConfig>}
+ */
 export async function load_config({ cwd = process.cwd() } = {}) {
 	const config_file = path.join(cwd, 'svelte.config.js');
 
@@ -74,6 +81,7 @@ export function validate_config(config) {
 }
 
 /**
+ * Ensures the user does not override any config values that SvelteKit must control.
  * @param {string[]} conflicts - array of conflicts in dotted notation
  * @param {string=} pathPrefix - prepended in front of the path
  * @param {string=} scope - used to prefix the whole error message

packages/kit/src/core/generate_manifest/index.js

@@ -3,6 +3,8 @@ import { parse_route_id } from '../../utils/routing.js';
 import { get_mime_lookup } from '../utils.js';
 
 /**
+ * Generates the data used to write the server-side manifest.js file. This data is used in the Vite
+ * build process, to power routing, etc.
  * @param {{
  *   build_data: import('types').BuildData;
  *   relative_path: string;

packages/kit/src/core/sync/write_manifest.js

@@ -3,6 +3,8 @@ import { s } from '../../utils/misc.js';
 import { trim, write_if_changed } from './utils.js';
 
 /**
+ * Writes the client manifest to disk. The manifest is used to power the router. It contains the
+ * list of routes and corresponding Svelte components (i.e. pages and layouts).
  * @param {import('types').ManifestData} manifest_data
  * @param {string} base
  * @param {string} output

packages/kit/src/core/sync/write_tsconfig.js

@@ -7,7 +7,10 @@ import { write_if_changed } from './utils.js';
 /** @param {string} file */
 const exists = (file) => fs.existsSync(file) && file;
 
-/** @param {import('types').ValidatedKitConfig} config */
+/**
+ * Writes the tsconfig that the user's tsconfig inherits from.
+ * @param {import('types').ValidatedKitConfig} config
+ */
 export function write_tsconfig(config, cwd = process.cwd()) {
 	const out = path.join(config.outDir, 'tsconfig.json');
 	const user_file =

packages/kit/src/runtime/server/page/load_node.js

@@ -9,6 +9,7 @@ import { coalesce_to_error } from '../../../utils/error.js';
 import { domain_matches, path_matches } from './cookie.js';
 
 /**
+ * Calls the user's `load` function.
  * @param {{
  *   event: import('types').RequestEvent;
  *   options: import('types').SSROptions;

packages/kit/src/runtime/server/page/render.js

@@ -15,6 +15,7 @@ const updated = {
 };
 
 /**
+ * Creates the HTML response.
  * @param {{
  *   branch: Array<import('./types').Loaded>;
  *   options: import('types').SSROptions;

packages/kit/src/runtime/server/page/respond.js

@@ -11,6 +11,7 @@ import { coalesce_to_error } from '../../../utils/error.js';
  */
 
 /**
+ * Gets the nodes, calls `load` for each of them, and then calls render to build the HTML response.
  * @param {{
  *   event: import('types').RequestEvent;
  *   options: SSROptions;