From cae13b582c7790a98df9409737f6660ed10f0aa9 Mon Sep 17 00:00:00 2001
From: Aryaman Dhingra <aryamandhingra@bitgo.com>
Date: Fri, 23 Aug 2024 11:00:03 -0400
Subject: [PATCH] docs: add comments to unchecked routes

DX-704
---
 packages/typed-express-router/src/types.ts  | 75 +++++++++++++++++++++
 packages/typed-express-router/tsconfig.json |  3 +-
 2 files changed, 77 insertions(+), 1 deletion(-)

diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts
index 0954df0a..fd548dcd 100644
--- a/packages/typed-express-router/src/types.ts
+++ b/packages/typed-express-router/src/types.ts
@@ -123,9 +123,84 @@ export type WrappedRouter<Spec extends ApiSpec> = Omit<
     put: AddRouteHandler<Spec, 'put'>;
     delete: AddRouteHandler<Spec, 'delete'>;
     patch: AddRouteHandler<Spec, 'patch'>;
+    /**
+     * This function will create a GET route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     getUnchecked: AddUncheckedRouteHandler<Spec, 'get'>;
+    /**
+     * This function will create a POST route without validating the request body, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     postUnchecked: AddUncheckedRouteHandler<Spec, 'post'>;
+    /**
+     * This function will create a PUT route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     putUnchecked: AddUncheckedRouteHandler<Spec, 'put'>;
+    /**
+     * This function will create a DELETE route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     deleteUnchecked: AddUncheckedRouteHandler<Spec, 'delete'>;
+    /**
+     * This function will create a PATCH route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     patchUnchecked: AddUncheckedRouteHandler<Spec, 'patch'>;
   };
diff --git a/packages/typed-express-router/tsconfig.json b/packages/typed-express-router/tsconfig.json
index 4433521c..dd120ada 100644
--- a/packages/typed-express-router/tsconfig.json
+++ b/packages/typed-express-router/tsconfig.json
@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.json",
   "include": ["src/**/*", "test/**/*"],
   "compilerOptions": {
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "removeComments": false
   },
   "references": [
     {