Adding JSDocs for all public symbols (#823)

* Adding JSDocs for all public symbols

* adding more jsdocs

* Change docs in page and applyProps

blocks/page.tsx

@@ -7,6 +7,18 @@ import { createSectionBlock, type SectionModule } from "./section.ts";
 
 export type Page = InstanceOf<typeof page, "#/root/pages">;
 
+/**
+ * Defines a Page block. 
+ * Pages are JSX-based components and can be rendered by any JSX-compliant library like react or preact.
+ *
+ * @param {any} component - The component or element to be used in the section.
+ * @param {Function} ComponentFunc - A function that renders the component.
+ * @returns {Block<SectionModule<any, any, any, any>, ResolverLike<any>, string, any, any>}
+ *   A Block object with properties:
+ *   - `Component`: The rendered component.
+ *   - `props`: Props passed to the component.
+ *   - `metadata`: Metadata about the section, including `resolveChain` and `component`.
+ */
 const page: Block<
   SectionModule<any, any, any, any>,
   ResolverLike<any>,

blocks/utils.tsx

@@ -154,7 +154,17 @@ export const fnContextFromHttpContext = <TState = {}>(
       return isBot ??= isUABot(ctx.request);
     },
   };
+
 };
+/**
+ *  Applies the given props to the target block function.
+ *
+ * @template TProps, TResp
+ * @param {Object} func - A function with a `default` property.
+ * @param {TProps} $live - Props to be applied to the function.
+ * @param {HttpContext<{ global: any } & RequestState>} ctx - A context object containing global state and request information.
+ * @returns {PromiseOrValue<TResp>} The result of the function call with the applied props.
+ */
 export const applyProps = <
   TProps = any,
   TResp = any,

components/JsonViewer.tsx

@@ -44,6 +44,12 @@ const snippet = (json: string) => {
   );
 };
 
+/**
+ * Renders a JSON object in a formatted and interactive way.
+ *
+ * @param {Props} p - Props for the JSON viewer component.
+ * @returns {JSX.Element} The rendered JSON viewer component.
+ */
 export default function JsonViewer(p: Props): JSX.Element {
   const { Head } = useFramework();
   return (

components/section.tsx

@@ -28,6 +28,9 @@ export interface SectionContext extends HttpContext<RequestState> {
   FallbackWrapper: ComponentType<any>;
 }
 
+/**
+ * Preact context for storing section context.
+ */
 export const SectionContext: PreactContext<SectionContext | undefined> =
   createContext<SectionContext | undefined>(
     undefined,

deco.ts

@@ -119,21 +119,49 @@ export const Context = {
   },
 };
 
+/**
+ * Provides methods for accessing and binding request context.
+ */
 export const RequestContext: RequestContextBinder = {
+  /**
+   * Returns the active request context.
+   *
+   * @returns {RequestContext | undefined} The active request context.
+   */
   active: (): RequestContext | undefined => Context.active().request,
+
+  /**
+   * Binds a function to the given request context.
+   *
+   * @template R, TArgs
+   * @param {RequestContext} request - The request context.
+   * @param {Function} f - The function to bind.
+   * @returns {Function} The bound function.
+   */
   bind: <R, TArgs extends unknown[]>(
     request: RequestContext,
     f: (...args: TArgs) => R,
   ): (...args: TArgs) => R => {
     return Context.bind({ ...Context.active(), request }, f);
   },
+
+  /**
+   * Gets the request's signal.
+   *
+   * @returns {AbortSignal | undefined} The request's signal.
+   */
   get signal() {
     return Context.active().request?.signal;
   },
+
+  /**
+   * Gets the request's framework.
+   *
+   * @returns {string} The request's framework. Defaults to "fresh".
+   */
   get framework() {
     return Context.active().request?.framework ?? "fresh";
   },
 };
-
 // deno-lint-ignore no-explicit-any
 export const context: DecoContext<any> = Context.active();

hooks/useDevice.ts

@@ -1,8 +1,14 @@
 import { useContext } from "preact/hooks";
 
 import { SectionContext } from "../components/section.tsx";
-import { Device } from "../utils/userAgent.ts";
+import type { Device } from "../utils/userAgent.ts";
 
+/**
+ * Hook to access the device information.
+ *
+ * @throws {Error}  - Throws an error if used on the browser or when context is missing.
+ * @returns {Device} The device information.
+ */
 export const useDevice = (): Device => {
   const ctx = useContext(SectionContext);
 

hooks/usePartialSection.ts

@@ -12,6 +12,13 @@ interface PartialSectionAttrs {
   "f-partial": string;
 }
 
+/**
+ * Hook to create attributes for a partial section component.
+ *
+ * @template P - Type of the partial section props
+ * @param {Options<P>} props - Optional props for the partial section.
+ * @returns {PartialSectionAttrs} An object containing attributes for the partial section.
+ */
 export const usePartialSection = <P>(
   props: Options<P> = {},
 ): PartialSectionAttrs => ({

hooks/useScript.ts

@@ -59,6 +59,14 @@ const minify = async (js: string) => {
   }
 };
 
+/**
+ * Hook to create a minified script tag from a function.
+ *
+ * @template T - Type of the function to be used as script
+ * @param {T} fn - The function to be included as a script.
+ * @param {...Parameters<T>} params - Parameters to be passed to the function.
+ * @returns {string} The minified script tag content.
+ */
 export function useScript<T extends (...args: any[]) => any>(
   fn: T,
   ...params: Parameters<T>

runtime/features/invoke.ts

@@ -44,6 +44,12 @@ const isInvokeFunc = (
   return (p as InvokeFunction).key !== undefined;
 };
 
+/**
+ * Converts an invoke payload into a resolvable object.
+ *
+ * @param {InvokePayload<any>} p - The invoke payload.
+ * @returns {Resolvable} The resolvable object.
+ */
 export const payloadToResolvable = (
   p: InvokePayload<any>,
 ): Resolvable => {
@@ -58,6 +64,13 @@ export const payloadToResolvable = (
   return resolvable;
 };
 
+/**
+ * Invokes multiple payloads in a batch.
+ *
+ * @param {InvokePayload<any>} payload - The batch payload containing invocations.
+ * @param {State<any>} state - The application state.
+ * @returns {Promise<any>} Promise resolving to the result of the batch invocation.
+ */
 export const batchInvoke = (
   payload: InvokePayload<any>,
   state: State<any>,
@@ -70,6 +83,15 @@ export const batchInvoke = (
   ).catch(wrapInvokeErr(state.correlationId ?? crypto.randomUUID()));
 };
 
+/**
+ * Invokes a function within the application state.
+ *
+ * @param {InvokeFunction["key"]} key - The key of the function to invoke.
+ * @param {InvokeFunction["props"]} props - Props to be passed to the function.
+ * @param {InvokeFunction["select"]} select - The selection path for the function.
+ * @param {State<any>} state - The application state.
+ * @returns {Promise<any>} Promise resolving to the result of the invocation.
+ */
 export const invoke = async (
   key: InvokeFunction["key"],
   props: InvokeFunction["props"],

runtime/fetch/mod.ts

@@ -13,6 +13,13 @@ interface FechInfo {
   ): Promise<Response>;
 }
 
+/**
+ * A modified fetch function that includes logging and caching features.
+ *
+ * @type {FechInfo}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/fetch}
+ */
+
 export const fetch: FechInfo = [
   withLogs,
   ENABLE_LOADER_CACHE ? undefined : withCache,

runtime/handler.tsx

@@ -95,14 +95,30 @@ const routes: Array<
   },
 ];
 
+/**
+ * Preact context for storing the application framework.
+ */
 export const FrameworkContext = createContext<Framework | undefined>(
   undefined,
 );
 
+/**
+ * Hook to access the application framework from context.
+ *
+ * @throws {Error}  - Throws an error if framework is not set in context.
+ * @returns {Framework} The application framework.
+ */
 export const useFramework = (): Framework => {
   return useContext(FrameworkContext)!;
 };
 
+/**
+ * Creates a handler function for a decorated application manifest.
+ *
+ * @template TAppManifest extends AppManifest = AppManifest - Type of the application manifest.
+ * @param {Deco<TAppManifest>} deco - The decorated application manifest.
+ * @returns {(req: Request, bindings?: DecoRouteState<TAppManifest>["Bindings"]) => Promise<Response> | Response} - The handler function for the application.
+ */
 export const handlerFor = <TAppManifest extends AppManifest = AppManifest>(
   deco: Deco<TAppManifest>,
 ): (

runtime/routes/entrypoint.tsx

@@ -23,6 +23,11 @@ const ctx = createContext<PageContext | undefined>(undefined);
 
 const routerCtx = createContext<RouterContext | undefined>(undefined);
 
+/**
+ * Hook to access the page context.
+ *
+ * @returns {PageContext | undefined} The page context, or undefined if not available.
+ */
 export const usePageContext = (): PageContext | undefined => {
   const pageCtx = useContext(ctx);
   if (pageCtx === undefined) {
@@ -33,6 +38,11 @@ export const usePageContext = (): PageContext | undefined => {
   return pageCtx;
 };
 
+/**
+ * Hook to access the router context.
+ *
+ * @returns {RouterContext | undefined} The router context, or undefined if not available.
+ */
 export const useRouterContext = (): RouterContext | undefined => {
   const routerCtxImpl = useContext(routerCtx);
   if (routerCtxImpl === undefined) {