chore: docs reference (#1509)

Co-authored-by: Ryan Carniato <[email protected]>
solidjs · May 28, 2024 · f604137 · f604137
1 parent c3290f1
commit f604137
Show file tree

Hide file tree

Showing 14 changed files with 116 additions and 41 deletions.
diff --git a/packages/start/config/index.d.ts b/packages/start/config/index.d.ts
@@ -6,7 +6,7 @@ import type { Options } from "vite-plugin-solid";
 // atleast until we sort which server options are good to use
 type ViteCustomizableConfig = CustomizableConfig & {
   server?: InlineConfig["server"];
-}
+};
 
 type SolidStartInlineConfig = {
   ssr?: boolean;
@@ -16,13 +16,19 @@ type SolidStartInlineConfig = {
   appRoot?: string;
   routeDir?: string;
   middleware?: string;
-  devOverlay?:  boolean;
+  devOverlay?: boolean;
   experimental?: {
     islands?: boolean;
-  }
+  };
   vite?:
     | ViteCustomizableConfig
     | ((options: { router: "server" | "client" | "server-function" }) => ViteCustomizableConfig);
 };
 
-export declare function defineConfig(baseConfig?: SolidStartInlineConfig): ReturnType<typeof createApp>;
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/entrypoints/app-config
+ */
+export declare function defineConfig(
+  baseConfig?: SolidStartInlineConfig
+): ReturnType<typeof createApp>;
diff --git a/packages/start/src/client/StartClient.tsx b/packages/start/src/client/StartClient.tsx
@@ -9,6 +9,10 @@ function Dummy(props: { children: JSX.Element }) {
   return props.children;
 }
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/client/start-client
+ */
 export function StartClient() {
   return (
     <Dummy>

diff --git a/packages/start/src/client/islands.tsx b/packages/start/src/client/islands.tsx
@@ -1,5 +1,10 @@
 // @refresh skip
 import "vinxi/client";
+
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/client/start-client
+ */
 export function StartClient() {
   return null;
 }

diff --git a/packages/start/src/client/mount.ts b/packages/start/src/client/mount.ts
@@ -1,7 +1,17 @@
 import type { JSX } from "solid-js";
 import { createStore } from "solid-js/store";
-import { createComponent, getHydrationKey, getOwner, hydrate, type MountableElement } from "solid-js/web";
+import {
+  createComponent,
+  getHydrationKey,
+  getOwner,
+  hydrate,
+  type MountableElement
+} from "solid-js/web";
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/client/mount
+ */
 export function mount(fn: () => JSX.Element, el: MountableElement) {
   if (import.meta.env.START_ISLANDS) {
     const map = new WeakMap();
@@ -20,7 +30,8 @@ export function mount(fn: () => JSX.Element, el: MountableElement) {
 
       let mod = await import(
         /* @vite-ignore */
-        import.meta.env.MANIFEST["client"]!.chunks[el.dataset.id!.split("#")[0] as string]!.output.path
+        import.meta.env.MANIFEST["client"]!.chunks[el.dataset.id!.split("#")[0] as string]!.output
+          .path
       );
       if (!mod || !el.dataset.hk) return;
 
@@ -69,7 +80,11 @@ export function mount(fn: () => JSX.Element, el: MountableElement) {
       Promise.all(
         [...assets].map(
           asset =>
-            import(/* @vite-ignore */import.meta.env.MANIFEST["client"]!.chunks[asset.split("#")[0] as string]!.output.path)
+            import(
+              /* @vite-ignore */ import.meta.env.MANIFEST["client"]!.chunks[
+                asset.split("#")[0] as string
+              ]!.output.path
+            )
         )
       )
         .then(() => {

diff --git a/packages/start/src/router/FileRoutes.ts b/packages/start/src/router/FileRoutes.ts
@@ -14,13 +14,15 @@ export function createRoutes() {
         ...(route.$$route ? route.$$route.require().route.info : {}),
         filesystem: true
       },
-      component: route.$component && lazyRoute(
-        route.$component,
-        import.meta.env.START_ISLANDS
-          ? import.meta.env.MANIFEST["ssr"]
-          : import.meta.env.MANIFEST["client"],
-        import.meta.env.MANIFEST["ssr"]
-      ),
+      component:
+        route.$component &&
+        lazyRoute(
+          route.$component,
+          import.meta.env.START_ISLANDS
+            ? import.meta.env.MANIFEST["ssr"]
+            : import.meta.env.MANIFEST["client"],
+          import.meta.env.MANIFEST["ssr"]
+        ),
       children: route.children ? route.children.map(createRoute) : undefined
     };
   }
@@ -29,6 +31,11 @@ export function createRoutes() {
 }
 
 let routes: any[];
+
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/routing/file-routes
+ */
 export const FileRoutes = isServer
   ? () => (getRequestEvent() as PageEvent).routes
   : () => routes || (routes = createRoutes());
diff --git a/packages/start/src/server/StartServer.tsx b/packages/start/src/server/StartServer.tsx
@@ -31,12 +31,16 @@ function matchRoute(matches: any[], routes: any[], matched = []): any[] | undefi
   }
 }
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/start-server
+ */
 export function StartServer(props: { document: Component<DocumentComponentProps> }) {
   const context = getRequestEvent() as PageEvent;
   // @ts-ignore
   const nonce = context.nonce;
 
-  let assets: Asset[]  = [];
+  let assets: Asset[] = [];
   Promise.resolve().then(async () => {
     let assetPromises: Promise<Asset[]>[] = [];
     // @ts-ignore

diff --git a/packages/start/src/server/handler.ts b/packages/start/src/server/handler.ts
@@ -124,6 +124,10 @@ function handleStreamCompleteRedirect(context: PageEvent) {
   };
 }
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/create-handler
+ */
 export function createHandler(
   fn: (context: PageEvent) => unknown,
   options?: HandlerOptions | ((context: PageEvent) => HandlerOptions | Promise<HandlerOptions>)

diff --git a/packages/start/src/server/serverFunction.tsx b/packages/start/src/server/serverFunction.tsx
@@ -1,6 +1,10 @@
 import { getRequestEvent } from "solid-js/web";
 import type { ServerFunctionMeta } from "./types";
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/get-server-function-meta
+ */
 export function getServerFunctionMeta(): ServerFunctionMeta | undefined {
   return getRequestEvent()?.locals.serverFunctionMeta;
 }
diff --git a/packages/start/src/server/spa/StartServer.tsx b/packages/start/src/server/spa/StartServer.tsx
@@ -7,6 +7,10 @@ import type { DocumentComponentProps, PageEvent } from "../types";
 
 const docType = ssr("<!DOCTYPE html>");
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/start-server
+ */
 export function StartServer(props: { document: Component<DocumentComponentProps> }) {
   const context = getRequestEvent() as PageEvent;
   // @ts-ignore

diff --git a/packages/start/src/server/spa/handler.ts b/packages/start/src/server/spa/handler.ts
@@ -1,6 +1,10 @@
 import { createBaseHandler } from "../handler";
 import { FetchEvent, HandlerOptions, PageEvent } from "../types";
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/create-handler
+ */
 export function createHandler(
   fn: (context: PageEvent) => unknown,
   options?: HandlerOptions | ((context: PageEvent) => HandlerOptions)

diff --git a/packages/start/src/shared/GET.ts b/packages/start/src/shared/GET.ts
@@ -1,5 +1,9 @@
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/get
+ */
 export function GET<T extends (...args: any[]) => any>(fn: T) {
   return (...args: Parameters<T>) => {
     return (fn as any).GET(...args) as ReturnType<T>;
   };
-}
+}
diff --git a/packages/start/src/shared/HttpHeader.tsx b/packages/start/src/shared/HttpHeader.tsx
@@ -9,27 +9,31 @@ export interface HttpHeaderProps {
   append?: boolean;
 }
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/http-header
+ */
 export const HttpHeader = isServer
   ? (props: HttpHeaderProps) => {
-    const event = getRequestEvent() as PageEvent;
+      const event = getRequestEvent() as PageEvent;
 
-    if (props.append) event.response.headers.append(props.name, props.value);
-    else event.response.headers.set(props.name, props.value);
+      if (props.append) event.response.headers.append(props.name, props.value);
+      else event.response.headers.set(props.name, props.value);
 
-    onCleanup(() => {
-      if (event.nativeEvent.handled || event.complete) return;
-      const value = event.response.headers.get(props.name);
-      if (!value) return;
-      if (!value.includes(", ")) {
-        if (value === props.value) event.response.headers.delete(props.name);
-        return;
-      }
-      const values = value.split(", ");
-      const index = values.indexOf(props.value);
-      index !== -1 && values.splice(index, 1);
-      if (values.length) event.response.headers.set(props.name, values.join(","));
-      else event.response.headers.delete(props.name);
-    });
-    return null;
-  }
+      onCleanup(() => {
+        if (event.nativeEvent.handled || event.complete) return;
+        const value = event.response.headers.get(props.name);
+        if (!value) return;
+        if (!value.includes(", ")) {
+          if (value === props.value) event.response.headers.delete(props.name);
+          return;
+        }
+        const values = value.split(", ");
+        const index = values.indexOf(props.value);
+        index !== -1 && values.splice(index, 1);
+        if (values.length) event.response.headers.set(props.name, values.join(","));
+        else event.response.headers.delete(props.name);
+      });
+      return null;
+    }
   : (_props: HttpHeaderProps) => null;
diff --git a/packages/start/src/shared/HttpStatusCode.tsx b/packages/start/src/shared/HttpStatusCode.tsx
@@ -8,12 +8,18 @@ export interface HttpStatusCodeProps {
   text?: string;
 }
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/server/http-status-code
+ */
 export const HttpStatusCode = isServer
   ? (props: HttpStatusCodeProps) => {
-    const event = getRequestEvent() as PageEvent;
-    event.response.status = props.code;
-    event.response.statusText = props.text;
-    onCleanup(() => !event.nativeEvent.handled && !event.complete && (event.response.status = 200));
-    return null;
-  }
+      const event = getRequestEvent() as PageEvent;
+      event.response.status = props.code;
+      event.response.statusText = props.text;
+      onCleanup(
+        () => !event.nativeEvent.handled && !event.complete && (event.response.status = 200)
+      );
+      return null;
+    }
   : (_props: HttpStatusCodeProps) => null;
diff --git a/packages/start/src/shared/clientOnly.tsx b/packages/start/src/shared/clientOnly.tsx
@@ -3,6 +3,10 @@ import type { Component, ComponentProps, JSX } from "solid-js";
 import { createMemo, createSignal, onMount, sharedConfig, splitProps, untrack } from "solid-js";
 import { isServer } from "solid-js/web";
 
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/client/client-only
+ */
 // not using Suspense
 export default function clientOnly<T extends Component<any>>(
   fn: () => Promise<{