docs: improve jsdocs

src/types/handler.ts

@@ -4,7 +4,12 @@ import type { OperationObject, OpenAPI3, Extensable } from "../types/openapi-ts.
 
 type MaybeArray<T> = T | T[];
 
-/** @experimental */
+/**
+ * Route-level metadata attached to event handlers.
+ *
+ * @experimental
+ * @see https://nitro.build/docs/routing
+ */
 export interface NitroRouteMeta {
   openAPI?: OperationObject & {
     $global?: Pick<OpenAPI3, "components"> & Extensable;
@@ -13,38 +18,53 @@ export interface NitroRouteMeta {
 
 interface NitroHandlerCommon {
   /**
-   * HTTP pathname pattern to match
+   * HTTP pathname pattern to match.
    *
-   * Examples: `/test`, `/api/:id`, `/blog/**`
+   * @example "/test", "/api/:id", "/blog/**"
    */
   route: string;
 
   /**
-   * HTTP method to match
+   * HTTP method to match.
    */
   method?: HTTPMethod;
 
   /**
-   * Run handler as a middleware before other route handlings
+   * Run handler as a middleware before other route handlers.
    */
   middleware?: boolean;
 
   /**
-   * Extra Meta
+   * Route metadata (e.g. OpenAPI operation info).
    */
   meta?: NitroRouteMeta;
 }
 
+/**
+ * Handler module format.
+ *
+ * - `"web"` — standard Web API handler (default).
+ * - `"node"` — Node.js-style handler, automatically converted to web-compatible.
+ */
 export type EventHandlerFormat = "web" | "node";
 
+/**
+ * Event handler registration for build-time bundling.
+ *
+ * Handlers are file references that the bundler imports and transforms.
+ * For runtime-only handlers in development, use {@link NitroDevEventHandler}.
+ *
+ * @see https://nitro.build/config#handlers
+ * @see https://nitro.build/docs/routing
+ */
 export interface NitroEventHandler extends NitroHandlerCommon {
   /**
-   * Use lazy loading to import handler
+   * Use lazy loading to import handler.
    */
   lazy?: boolean;
 
   /**
-   * Path to event handler
+   * Path to event handler.
    */
   handler: string;
 
@@ -55,21 +75,43 @@ export interface NitroEventHandler extends NitroHandlerCommon {
    */
   format?: EventHandlerFormat;
 
-  /*
-   * Environments to include and bundle this handler
+  /**
+   * Environments to include and bundle this handler.
+   *
+   * @example
+   * ```ts
+   * env: ["dev", "prod"]
+   * env: "prerender"
+   * ```
    */
   env?: MaybeArray<"dev" | "prod" | "prerender" | PresetName | (string & {})>;
 }
 
+/**
+ * Development-only event handler with an inline handler function.
+ *
+ * These handlers are available only during `nitro dev` and are not
+ * included in production builds.
+ *
+ * @see https://nitro.build/config#devhandlers
+ */
 export interface NitroDevEventHandler extends NitroHandlerCommon {
   /**
-   * Event handler function
+   * Event handler function.
    */
   handler: HTTPHandler;
 }
 
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Custom error handler function signature.
+ *
+ * Receives the error, the H3 event, and a helper object containing the
+ * `defaultHandler` for fallback rendering.
+ *
+ * @see https://nitro.build/config#errorhandler
+ */
 export type NitroErrorHandler = (
   error: HTTPError,
   event: HTTPEvent,

src/types/module.ts

@@ -1,7 +1,35 @@
 import type { Nitro } from "./nitro.ts";
 
+/**
+ * Accepted input formats for Nitro modules.
+ *
+ * Can be a module path string, a {@link NitroModule} object, a bare setup
+ * function, or an object with a `nitro` key containing a {@link NitroModule}.
+ *
+ * @see https://nitro.build/config#modules
+ */
 export type NitroModuleInput = string | NitroModule | NitroModule["setup"] | { nitro: NitroModule };
 
+/**
+ * A Nitro module that extends behavior during initialization.
+ *
+ * Modules receive the {@link Nitro} instance and can register hooks,
+ * add handlers, modify options, or perform other setup tasks.
+ *
+ * @example
+ * ```ts
+ * const myModule: NitroModule = {
+ *   name: "my-module",
+ *   setup(nitro) {
+ *     nitro.hooks.hook("compiled", () => {
+ *       console.log("Build complete!");
+ *     });
+ *   },
+ * };
+ * ```
+ *
+ * @see https://nitro.build/config#modules
+ */
 export interface NitroModule {
   name?: string;
   setup: (this: void, nitro: Nitro) => void | Promise<void>;

src/types/nitro.ts

@@ -14,12 +14,20 @@ import type { WorkerAddress } from "./runner.ts";
 
 type MaybeArray<T> = T | T[];
 
+/** Nitro package metadata including version information. */
 export interface NitroMeta {
   version: string;
   majorVersion: number;
-  [key: string]: unknown;
 }
 
+/**
+ * The core Nitro instance available throughout the build lifecycle.
+ *
+ * Provides access to resolved options, hooks, the virtual file system,
+ * scanned handlers, and utility methods.
+ *
+ * @see https://nitro.build/docs/lifecycle
+ */
 export interface Nitro {
   meta: NitroMeta;
   options: NitroOptions;
@@ -44,19 +52,35 @@ export interface Nitro {
   _prerenderMeta?: Record<string, { contentType?: string }>;
 }
 
+/**
+ * Subset of {@link NitroConfig} that can be updated at runtime via
+ * `nitro.updateConfig()`.
+ */
 export type NitroDynamicConfig = Pick<NitroConfig, "runtimeConfig" | "routeRules">;
 
 export type NitroTypes = {
   routes: Record<string, Partial<Record<HTTPMethod | "default", string[]>>>;
   tsConfig?: TSConfig;
 };
 
+/**
+ * Metadata about the higher-level framework using Nitro (e.g. Nuxt).
+ *
+ * Used by presets and included in build info output.
+ *
+ * @see https://nitro.build/config#framework
+ */
 export interface NitroFrameworkInfo {
   name?: "nitro" | (string & {});
   version?: string;
 }
 
-/** Build info written to `.output/nitro.json` or `.nitro/dev/nitro.json` */
+/**
+ * Build info written to `.output/nitro.json` (production) or
+ * `node_modules/.nitro/nitro.dev.json` (development).
+ *
+ * Contains preset, framework, version, and command information.
+ */
 export interface NitroBuildInfo {
   date: string;
   preset: PresetName;

src/types/openapi.ts

@@ -1,7 +1,7 @@
 // import type { ApiReferenceConfiguration as ScalarConfig } from "@scalar/api-reference";
 
 /**
- * Swagger UI configuration options
+ * Swagger UI configuration options.
  *
  * @see https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
  */
@@ -32,13 +32,14 @@ export interface SwaggerUIConfig {
 }
 
 /**
- * Nitro OpenAPI configuration
+ * Nitro OpenAPI configuration.
  *
+ * @see https://nitro.build/config#openapi
  * @see https://nitro.build/docs/openapi
  */
 export interface NitroOpenAPIConfig {
   /**
-   * OpenAPI meta information
+   * OpenAPI document metadata.
    */
   meta?: {
     title?: string;
@@ -47,46 +48,56 @@ export interface NitroOpenAPIConfig {
   };
 
   /**
-   * OpenAPI json route
+   * Route for the OpenAPI JSON endpoint.
    *
-   * Default is `/_openapi.json`
+   * @default "/_openapi.json"
    */
   route?: string;
 
   /**
-   * Enable OpenAPI generation for production builds
+   * Enable OpenAPI generation for production builds.
+   *
+   * - `"runtime"` — generate at runtime (allows middleware usage).
+   * - `"prerender"` — prerender the JSON response at build time (most efficient).
+   * - `false` — disable in production.
+   *
+   * @see https://nitro.build/config#openapi
    */
   production?: false | "runtime" | "prerender";
 
   /**
-   * UI configurations
+   * UI configurations for interactive API documentation.
    */
   ui?: {
     /**
-     * Scalar UI configuration
+     * Scalar UI configuration.
+     *
+     * Set to `false` to disable.
      */
     scalar?:
       | false
       | (Partial<unknown> & {
           /**
-           * Scalar UI route
+           * Route for Scalar UI.
            *
-           * Default is `/_scalar`
+           * @default "/_scalar"
            */
           route?: string;
         });
     /**
-     * Swagger UI configuration
+     * Swagger UI configuration.
+     *
+     * Set to `false` to disable.
      *
      * @see https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
      */
     swagger?:
       | false
       | (SwaggerUIConfig & {
           /**
-           * Swagger UI route
+           * Route for Swagger UI.
            *
-           * Default is `/_swagger`
+           * @default "/_swagger"
            */
           route?: string;
         });