diff --git a/packages/start/src/middleware/index.ts b/packages/start/src/middleware/index.ts
index a0a578a42..19f068274 100644
--- a/packages/start/src/middleware/index.ts
+++ b/packages/start/src/middleware/index.ts
@@ -46,11 +46,28 @@ function wrapResponseMiddleware(onBeforeResponse: ResponseMiddleware): Middlewar
  * Creates middleware for handling requests and responses.
  *
  * @see https://docs.solidjs.com/solid-start/reference/server/create-middleware
+/**
+ * Creates request/response middlewares via H3.
+ *
+ * Accepts an array of H3 {@link Middleware}
+ *
+ * @tip To run your middleware before response, `await next()` in your function block.
+ *@example
+ * const middleware = createMiddleware([
+ *   async (event, next) => {
+ *     const resp = await next();
+ *     if (resp instanceof Response) return resp;
+ *     return new Response("Not found", { status: 404 });
+ *   },
+ * ]);
+ *
  */
 export function createMiddleware(
   args:
     | {
+        /** @deprecated Use H3 `Middleware` */
         onRequest?: RequestMiddleware | RequestMiddleware[] | undefined;
+        /** @deprecated Use H3 `Middleware` */
         onBeforeResponse?: ResponseMiddleware | ResponseMiddleware[] | undefined;
       }
     | Middleware[],