docs(httpkernel): enhance class and interface documentation

- Improve JSDoc comments for `HttpKernel` and `IHttpKernel` to clarify
  purpose, usage, and type parameters.
- Add detailed descriptions for methods, parameters, and generics.
- Refine explanations of middleware pipeline, error handling, and
  contextual typing.
- Enhance readability and consistency in public API documentation.

Signed-off-by: Max P. <Mail@MPassarello.de>

src/HttpKernel.ts

@@ -20,26 +20,37 @@ import { RouteBuilder } from './RouteBuilder.ts';
 import { createEmptyContext, normalizeError } from './Utils/mod.ts';
 
 /**
- * The central HTTP kernel responsible for managing route definitions,
- * executing middleware chains, and dispatching HTTP requests to their handlers.
+ * The `HttpKernel` is the central routing engine that manages the full HTTP request lifecycle.
  *
- * This class supports a fluent API for route registration and allows the injection
- * of custom response decorators and route builder factories for maximum flexibility and testability.
+ * It enables:
+ * - Dynamic and static route registration via a fluent API
+ * - Execution of typed middleware chains and final route handlers
+ * - Injection of response decorators and factory overrides
+ * - Fine-grained error handling via typed status-code-based handlers
+ *
+ * The kernel is designed with generics for flexible context typing, strong type safety,
+ * and a clear extension point for advanced routing, DI, or tracing logic.
+ *
+ * @typeParam TContext - The global context type used for all requests handled by this kernel.
  */
 export class HttpKernel<TContext extends IContext = IContext>
     implements IHttpKernel<TContext> {
     private cfg: IHttpKernelConfig<TContext>;
+
     /**
-     * The list of internally registered routes, each with method, matcher, middleware, and handler.
+     * The list of registered route definitions, including method, matcher,
+     * middleware pipeline, and final handler.
      */
     private routes: IInternalRoute<TContext>[] = [];
 
     /**
-     * Creates a new instance of the `HttpKernel`.
+     * Initializes the `HttpKernel` with optional configuration overrides.
      *
-     * @param decorateResponse - An optional response decorator function that is applied to all responses
-     *                           after the middleware/handler pipeline. Defaults to identity (no modification).
-     * @param routeBuilderFactory - Optional factory for creating route builders. Defaults to using `RouteBuilder`.
+     * Default components such as the route builder factory, response decorator,
+     * and 404/500 error handlers can be replaced by injecting a partial config.
+     * Any omitted values fall back to sensible defaults.
+     *
+     * @param config - Partial kernel configuration. Missing fields are filled with defaults.
      */
     public constructor(
         config?: DeepPartial<IHttpKernelConfig<TContext>>,
@@ -82,9 +93,8 @@ export class HttpKernel<TContext extends IContext = IContext>
 
     /**
      * @inheritdoc
-     */ public async handle(
-        request: Request,
-    ): Promise<Response> {
+     */
+    public async handle(request: Request): Promise<Response> {
         const url = new URL(request.url);
         const method = request.method.toUpperCase();
 
@@ -112,11 +122,12 @@ export class HttpKernel<TContext extends IContext = IContext>
     }
 
     /**
-     * Registers a finalized route by pushing it into the internal route list.
+     * Finalizes and registers a route within the kernel.
      *
-     * This method is typically called by the route builder after `.handle()` is invoked.
+     * This method is invoked internally by the route builder once
+     * `.handle()` is called. It appends the route to the internal list.
      *
-     * @param route - The fully constructed route including matcher, middlewares, and handler.
+     * @param route - A fully constructed internal route object.
      */
     private registerRoute<_TContext extends IContext = TContext>(
         route: IInternalRoute<_TContext>,
@@ -125,24 +136,18 @@ export class HttpKernel<TContext extends IContext = IContext>
     }
 
     /**
-     * Executes the complete request pipeline: middleware chain, final handler, and optional response decoration.
+     * Executes the middleware and handler pipeline for a matched route.
      *
-     * Middleware functions are invoked sequentially in the order of registration. Each middleware
-     * receives a `next()` callback to advance to the next stage. If a middleware returns a `Response`
-     * directly, the pipeline short-circuits.
+     * This function:
+     * - Enforces linear middleware execution with `next()` tracking
+     * - Validates middleware and handler types at runtime
+     * - Applies the optional response decorator post-processing
+     * - Handles all runtime errors via the configured 500 handler
      *
-     * After the final handler produces a response, it is passed through the configured response decorator,
-     * which may modify it (e.g., adding headers or logging metadata).
-     *
-     * Internal error handling ensures:
-     * - That `next()` is not called multiple times.
-     * - That all middleware and handlers are properly typed.
-     * - That thrown exceptions are routed to the 500-error handler.
-     *
-     * @param ctx - The current request context, including request data and shared state.
-     * @param middleware - An ordered list of middleware functions to invoke.
-     * @param handler - The terminal request handler to produce the response.
-     * @returns The final decorated `Response` object.
+     * @param ctx - The active request context passed to middleware and handler.
+     * @param middleware - Ordered middleware functions for this route.
+     * @param handler - The final handler responsible for generating a response.
+     * @returns The final HTTP `Response`, possibly decorated.
      */
     private async executePipeline(
         ctx: TContext,
@@ -158,7 +163,6 @@ export class HttpKernel<TContext extends IContext = IContext>
         let lastIndex = -1;
 
         const dispatch = async (currentIndex: number): Promise<Response> => {
-            // Prevent middleware from invoking next() multiple times
             if (currentIndex <= lastIndex) {
                 throw new Error('Middleware called `next()` multiple times');
             }

src/Interfaces/IHttpKernel.ts

@@ -3,48 +3,47 @@ import { IRouteBuilder } from './IRouteBuilder.ts';
 import { IRouteDefinition } from './IRouteDefinition.ts';
 
 /**
- * Defines the core interface for an HTTP kernel instance, responsible for
- * registering routes, orchestrating middleware pipelines, and dispatching
- * incoming HTTP requests to the appropriate handler.
+ * The `IHttpKernel` interface defines the public API for a type-safe, middleware-driven HTTP dispatching system.
  *
- * The kernel operates on a generic `IContext` type, which encapsulates the
- * request, typed state, route parameters, and query parameters for each request.
+ * Implementations of this interface are responsible for:
+ * - Registering routes with optional per-route context typing
+ * - Handling incoming requests by matching and dispatching to appropriate handlers
+ * - Managing the complete middleware pipeline and final response generation
  *
- * @template TContext The default context type for all registered routes and handlers.
+ * The kernel operates on a customizable `IContext` type to support strongly typed request parameters, state,
+ * and query values across the entire routing lifecycle.
+ *
+ * @typeParam TContext - The default context type used for all routes unless overridden per-route.
  */
 export interface IHttpKernel<TContext extends IContext = IContext> {
     /**
-     * Registers a new route using a static path or custom matcher.
+     * Registers a new HTTP route (static or dynamic) and returns a route builder for middleware/handler chaining.
      *
-     * Returns a route builder that allows chaining middleware and assigning a final handler.
-     * This method is context-generic, allowing temporary overrides for specific routes
-     * if their context differs from the kernel-wide default.
+     * This method supports contextual polymorphism via the `_TContext` type parameter, enabling fine-grained
+     * typing of route-specific `params`, `query`, and `state` values. The route is not registered until
+     * `.handle()` is called on the returned builder.
      *
-     * @template _TContext Optional context override for the specific route being registered.
-     *                     Defaults to the kernel's generic `TContext`.
+     * @typeParam _TContext - An optional override for the context type specific to this route.
+     *                        Falls back to the global `TContext` of the kernel if omitted.
      *
-     * @param definition - A route definition containing the HTTP method and either a path
-     *                     pattern (e.g., `/users/:id`) or a custom matcher function.
-     * @returns A fluent builder interface for attaching middleware and setting the handler.
+     * @param definition - A route definition specifying the HTTP method and path or custom matcher.
+     * @returns A fluent builder interface to define middleware and attach a final handler.
      */
     route<_TContext extends IContext = TContext>(
         definition: IRouteDefinition,
-    ): IRouteBuilder; // IRouteBuilder<_TContext>
+    ): IRouteBuilder<_TContext>;
 
     /**
-     * Handles an incoming HTTP request by matching it to a route, executing its middleware,
-     * and invoking the final handler. Automatically populates route parameters (`ctx.params`),
-     * query parameters (`ctx.query`), and initializes an empty mutable state (`ctx.state`).
+     * Handles an incoming HTTP request and produces a `Response`.
      *
-     * This method is typically passed directly to `Deno.serve()` as the request handler.
+     * The kernel matches the request against all registered routes by method and matcher,
+     * constructs a typed context, and executes the middleware/handler pipeline.
+     * If no route matches, a 404 error handler is invoked.
      *
-     * @template _TContext Optional override for the context type of the current request.
-     *                     Useful for testing or simulated requests. Defaults to the kernel’s `TContext`.
+     * This method is designed to be passed directly to `Deno.serve()` or similar server frameworks.
      *
-     * @param request - The incoming HTTP request to dispatch.
-     * @returns A promise resolving to the final HTTP response.
+     * @param request - The incoming HTTP request object.
+     * @returns A `Promise` resolving to a complete HTTP response.
      */
-    handle(
-        request: Request,
-    ): Promise<Response>;
+    handle(request: Request): Promise<Response>;
 }