docs: update jsdoc links

src/browser/setupWorker/glossary.ts

@@ -204,41 +204,53 @@ export type StopHandler = () => void
 export interface SetupWorker {
   /**
    * Registers and activates the mock Service Worker.
-   * @see {@link https://mswjs.io/docs/api/setup-worker/start `worker.start()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/start `worker.start()` API reference}
    */
   start: (options?: StartOptions) => StartReturnType
 
   /**
    * Stops requests interception for the current client.
-   * @see {@link https://mswjs.io/docs/api/setup-worker/stop `worker.stop()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/stop `worker.stop()` API reference}
    */
   stop: StopHandler
 
   /**
    * Prepends given request handlers to the list of existing handlers.
    * @param {RequestHandler[]} handlers List of runtime request handlers.
-   * @see {@link https://mswjs.io/docs/api/setup-worker/use `worker.use()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/use `worker.use()` API reference}
    */
   use: (...handlers: RequestHandler[]) => void
 
   /**
    * Marks all request handlers that respond using `res.once()` as unused.
-   * @see {@link https://mswjs.io/docs/api/setup-worker/restore-handlers `worker.restoreHandlers()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/restore-handlers `worker.restoreHandlers()` API reference}
    */
   restoreHandlers: () => void
 
   /**
    * Resets request handlers to the initial list given to the `setupWorker` call, or to the explicit next request handlers list, if given.
    * @param {RequestHandler[]} nextHandlers List of the new initial request handlers.
-   * @see {@link https://mswjs.io/docs/api/setup-worker/reset-handlers `worker.resetHandlers()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/reset-handlers `worker.resetHandlers()` API reference}
    */
   resetHandlers: (...nextHandlers: RequestHandler[]) => void
 
   /**
    * Returns a readonly list of currently active request handlers.
-   * @see {@link https://mswjs.io/docs/api/setup-worker/list-handlers `worker.listHandlers()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/list-handlers `worker.listHandlers()` API reference}
    */
   listHandlers(): ReadonlyArray<RequestHandler<RequestHandlerDefaultInfo, any>>
 
+  /**
+   * Life-cycle events.
+   * Life-cycle events allow you to subscribe to the internal library events occurring during the request/response handling.
+   *
+   * @see {@link https://mswjs.io/docs/api/life-cycle-events Life-cycle Events API reference}
+   */
   events: LifeCycleEventEmitter<LifeCycleEventsMap>
 }

src/browser/setupWorker/setupWorker.ts

@@ -187,7 +187,8 @@ export class SetupWorkerApi
 /**
  * Sets up a requests interception in the browser with the given request handlers.
  * @param {RequestHandler[]} handlers List of request handlers.
- * @see {@link https://mswjs.io/docs/api/setup-worker `setupWorker`}
+ *
+ * @see {@link https://mswjs.io/docs/api/setup-worker `setupWorker()` API reference}
  */
 export function setupWorker(...handlers: Array<RequestHandler>): SetupWorker {
   return new SetupWorkerApi(...handlers)

src/core/HttpResponse.ts

@@ -24,9 +24,15 @@ export interface StrictResponse<BodyType extends DefaultBodyType>
 }
 
 /**
- * A `Response` class superset with a stricter response body type.
+ * A drop-in replacement for the standard `Response` class
+ * to allow additional features, like mocking the response `Set-Cookie` header.
+ *
  * @example
  * new HttpResponse('Hello world', { status: 201 })
+ * HttpResponse.json({ name: 'John' })
+ * HttpResponse.formData(form)
+ *
+ * @see {@link https://mswjs.io/docs/api/http-response `HttpResponse` API reference}
  */
 export class HttpResponse extends Response {
   constructor(body?: BodyInit | null, init?: HttpResponseInit) {

src/core/bypass.ts

@@ -3,14 +3,16 @@ import { invariant } from 'outvariant'
 export type BypassRequestInput = string | URL | Request
 
 /**
- * Creates a `Request` instance that will always be bypassed by MSW.
+ * Creates a `Request` instance that will always be ignored by MSW.
  *
  * @example
  * import { bypass } from 'msw'
  *
  * fetch(bypass('/resource'))
  * fetch(bypass(new URL('/resource', 'https://example.com)))
  * fetch(bypass(new Request('https://example.com/resource')))
+ *
+ * @see {@link https://mswjs.io/docs/api/bypass `bypass()` API reference}
  */
 export function bypass(input: BypassRequestInput, init?: RequestInit): Request {
   const request = input instanceof Request ? input : new Request(input, init)

src/core/delay.ts

@@ -20,10 +20,13 @@ export type DelayMode = 'real' | 'infinite'
 
 /**
  * Delays the response by the given duration (ms).
+ *
  * @example
  * await delay() // emulate realistic server response time
  * await delay(1200) // delay response by 1200ms
  * await delay('infinite') // delay response infinitely
+ *
+ * @see {@link https://mswjs.io/docs/api/delay `delay()` API reference}
  */
 export async function delay(
   durationOrMode?: DelayMode | number,

src/core/graphql.test.ts

@@ -3,9 +3,9 @@ import { graphql } from './graphql'
 test('exports supported GraphQL operation types', () => {
   expect(graphql).toBeDefined()
   expect(Object.keys(graphql)).toEqual([
-    'operation',
     'query',
     'mutation',
+    'operation',
     'link',
   ])
 })

src/core/graphql.ts

@@ -67,35 +67,42 @@ function createGraphQLOperationHandler(url: Path) {
 }
 
 const standardGraphQLHandlers = {
-  /**
-   * Captures any GraphQL operation, regardless of its name, under the current scope.
-   * @example
-   * graphql.operation(() => {
-   *   return HttpResponse.json({ data: { name: 'John' } })
-   * })
-   * @see {@link https://mswjs.io/docs/api/graphql/operation `graphql.operation()`}
-   */
-  operation: createGraphQLOperationHandler('*'),
-
   /**
    * Captures a GraphQL query by a given name.
+   *
    * @example
    * graphql.query('GetUser', () => {
    *   return HttpResponse.json({ data: { user: { name: 'John' } } })
    * })
-   * @see {@link https://mswjs.io/docs/api/graphql/query `graphql.query()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphqlqueryqueryname-resolver `graphql.query()` API reference}
    */
   query: createScopedGraphQLHandler('query' as OperationTypeNode, '*'),
 
   /**
-   * Captures a GraphQL mutation by a given name.
+   * Intercepts a GraphQL mutation by its name.
+   *
    * @example
    * graphql.mutation('SavePost', () => {
    *   return HttpResponse.json({ data: { post: { id: 'abc-123 } } })
    * })
-   * @see {@link https://mswjs.io/docs/api/graphql/mutation `graphql.mutation()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphqlmutationmutationname-resolver `graphql.query()` API reference}
+   *
    */
   mutation: createScopedGraphQLHandler('mutation' as OperationTypeNode, '*'),
+
+  /**
+   * Intercepts any GraphQL operation, regardless of its type or name.
+   *
+   * @example
+   * graphql.operation(() => {
+   *   return HttpResponse.json({ data: { name: 'John' } })
+   * })
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphloperationresolver `graphql.operation()` API reference}
+   */
+  operation: createGraphQLOperationHandler('*'),
 }
 
 function createGraphQLLink(url: Path): typeof standardGraphQLHandlers {
@@ -106,7 +113,26 @@ function createGraphQLLink(url: Path): typeof standardGraphQLHandlers {
   }
 }
 
+/**
+ * A namespace to intercept and mock GraphQL operations
+ *
+ * @example
+ * graphql.query('GetUser', resolver)
+ * graphql.mutation('DeletePost', resolver)
+ *
+ * @see {@link https://mswjs.io/docs/api/graphql `graphql` API reference}
+ */
 export const graphql = {
   ...standardGraphQLHandlers,
+
+  /**
+   * Intercepts GraphQL operations scoped by the given URL.
+   *
+   * @example
+   * const github = graphql.link('https://api.github.com/graphql')
+   * github.query('GetRepo', resolver)
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphqllinkurl `graphql.link()` API reference}
+   */
   link: createGraphQLLink,
 }

src/core/http.ts

@@ -30,6 +30,15 @@ function createHttpHandler<Method extends HttpMethods | RegExp>(
   }
 }
 
+/**
+ * A namespace to intercept and mock HTTP requests.
+ *
+ * @example
+ * http.get('/user', resolver)
+ * http.post('/post/:id', resolver)
+ *
+ * @see {@link https://mswjs.io/docs/api/http `http` API reference}
+ */
 export const http = {
   all: createHttpHandler(/.+/),
   head: createHttpHandler(HttpMethods.HEAD),

src/core/passthrough.ts

@@ -1,5 +1,5 @@
 /**
- * Performs the captured request as-is.
+ * Performs the intercepted request as-is.
  *
  * This stops request handler lookup so no other handlers
  * can affect this request past this point.
@@ -9,6 +9,8 @@
  * http.get('/resource', () => {
  *   return passthrough()
  * })
+ *
+ * @see {@link https://mswjs.io/docs/api/passthrough `passthrough()` API reference}
  */
 export function passthrough(): Response {
   return new Response(null, {

src/native/index.ts

@@ -5,7 +5,8 @@ import { SetupServerApi } from '../node/SetupServerApi'
 /**
  * Sets up a requests interception in React Native with the given request handlers.
  * @param {RequestHandler[]} handlers List of request handlers.
- * @see {@link https://mswjs.io/docs/api/setup-server `setupServer`}
+ *
+ * @see {@link https://mswjs.io/docs/api/setup-server `setupServer()` API reference}
  */
 export function setupServer(
   ...handlers: Array<RequestHandler>

src/node/glossary.ts

@@ -12,39 +12,51 @@ import {
 export interface SetupServer {
   /**
    * Starts requests interception based on the previously provided request handlers.
-   * @see {@link https://mswjs.io/docs/api/setup-server/listen `server.listen()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-server/listen `server.listen()` API reference}
    */
   listen(options?: PartialDeep<SharedOptions>): void
 
   /**
    * Stops requests interception by restoring all augmented modules.
-   * @see {@link https://mswjs.io/docs/api/setup-server/close `server.close()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-server/close `server.close()` API reference}
    */
   close(): void
 
   /**
    * Prepends given request handlers to the list of existing handlers.
-   * @see {@link https://mswjs.io/docs/api/setup-server/use `server.use()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-server/use `server.use()` API reference}
    */
   use(...handlers: Array<RequestHandler>): void
 
   /**
    * Marks all request handlers that respond using `res.once()` as unused.
-   * @see {@link https://mswjs.io/docs/api/setup-server/restore-handlers `server.restore-handlers()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-server/restore-handlers `server.restore-handlers()` API reference}
    */
   restoreHandlers(): void
 
   /**
    * Resets request handlers to the initial list given to the `setupServer` call, or to the explicit next request handlers list, if given.
-   * @see {@link https://mswjs.io/docs/api/setup-server/reset-handlers `server.reset-handlers()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-server/reset-handlers `server.reset-handlers()` API reference}
    */
   resetHandlers(...nextHandlers: Array<RequestHandler>): void
 
   /**
    * Returns a readonly list of currently active request handlers.
-   * @see {@link https://mswjs.io/docs/api/setup-server/list-handlers `server.listHandlers()`}
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-server/list-handlers `server.listHandlers()` API reference}
    */
   listHandlers(): ReadonlyArray<RequestHandler<RequestHandlerDefaultInfo, any>>
 
+  /**
+   * Life-cycle events.
+   * Life-cycle events allow you to subscribe to the internal library events occurring during the request/response handling.
+   *
+   * @see {@link https://mswjs.io/docs/api/life-cycle-events Life-cycle Events API reference}
+   */
   events: LifeCycleEventEmitter<LifeCycleEventsMap>
 }

src/node/setupServer.ts

@@ -8,7 +8,8 @@ import { SetupServerApi } from './SetupServerApi'
 /**
  * Sets up a requests interception in Node.js with the given request handlers.
  * @param {RequestHandler[]} handlers List of request handlers.
- * @see {@link https://mswjs.io/docs/api/setup-server `setupServer`}
+ *
+ * @see {@link https://mswjs.io/docs/api/setup-server `setupServer()` API reference}
  */
 export const setupServer = (
   ...handlers: Array<RequestHandler>