@effect/platform 0.66.2 → 0.67.0

package/src/HttpApi.ts

@@ -134,21 +134,45 @@ export const empty: HttpApi = makeProto({
  * @category constructors
  */
 export const addGroup: {
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Group extends HttpApiGroup.HttpApiGroup.Any>(
     group: Group
   ): <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR>(
     self: HttpApi<Groups, Error, ErrorR>
   ) => HttpApi<Groups | Group, Error, ErrorR>
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Group extends HttpApiGroup.HttpApiGroup.Any>(
     path: HttpRouter.PathInput,
     group: Group
   ): <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR>(
     self: HttpApi<Groups, Error, ErrorR>
   ) => HttpApi<Groups | Group, Error, ErrorR>
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, Group extends HttpApiGroup.HttpApiGroup.Any>(
     self: HttpApi<Groups, Error, ErrorR>,
     group: Group
   ): HttpApi<Groups | Group, Error, ErrorR>
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, Group extends HttpApiGroup.HttpApiGroup.Any>(
     self: HttpApi<Groups, Error, ErrorR>,
     path: HttpRouter.PathInput,
@@ -178,6 +202,15 @@ export const addGroup: {
  * @category errors
  */
 export const addError: {
+  /**
+   * Add an error schema to an `HttpApi`, which is shared by all endpoints in the
+   * `HttpApi`.
+   *
+   * Useful for adding error types from middleware or other shared error types.
+   *
+   * @since 1.0.0
+   * @category errors
+   */
   <A, I, R>(
     schema: Schema.Schema<A, I, R>,
     annotations?: {
@@ -186,6 +219,15 @@ export const addError: {
   ): <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR>(
     self: HttpApi<Groups, Error, ErrorR>
   ) => HttpApi<Groups, Error | A, ErrorR | R>
+  /**
+   * Add an error schema to an `HttpApi`, which is shared by all endpoints in the
+   * `HttpApi`.
+   *
+   * Useful for adding error types from middleware or other shared error types.
+   *
+   * @since 1.0.0
+   * @category errors
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, A, I, R>(
     self: HttpApi<Groups, Error, ErrorR>,
     schema: Schema.Schema<A, I, R>,
@@ -219,7 +261,15 @@ export const addError: {
  * @category annotations
  */
 export const annotateMerge: {
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <I>(context: Context.Context<I>): <A extends HttpApi.Any>(self: A) => A
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApi.Any, I>(self: A, context: Context.Context<I>): A
 } = dual(
   2,
@@ -236,7 +286,15 @@ export const annotateMerge: {
  * @category annotations
  */
 export const annotate: {
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApi.Any>(self: A) => A
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApi.Any, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
 } = dual(
   3,

package/src/HttpApiBuilder.ts

@@ -57,10 +57,28 @@ export class Router extends HttpRouter.Tag("@effect/platform/HttpApiBuilder/Rout
  * @category constructors
  */
 export const serve: {
+  /**
+   * Build an `HttpApp` from an `HttpApi` instance, and serve it using an
+   * `HttpServer`.
+   *
+   * Optionally, you can provide a middleware function that will be applied to
+   * the `HttpApp` before serving.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   (): Layer.Layer<never, never, HttpServer.HttpServer | HttpApi.HttpApi.Service | HttpRouter.HttpRouter.DefaultServices>
-  <R>(
-    middleware: (httpApp: HttpApp.Default) => HttpApp.Default<never, R>
-  ): Layer.Layer<
+  /**
+   * Build an `HttpApp` from an `HttpApi` instance, and serve it using an
+   * `HttpServer`.
+   *
+   * Optionally, you can provide a middleware function that will be applied to
+   * the `HttpApp` before serving.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
+  <R>(middleware: (httpApp: HttpApp.Default) => HttpApp.Default<never, R>): Layer.Layer<
     never,
     never,
     | HttpServer.HttpServer
@@ -313,6 +331,12 @@ export const group = <
  * @category handlers
  */
 export const handle: {
+  /**
+   * Add the implementation for an `HttpApiEndpoint` to a `Handlers` group.
+   *
+   * @since 1.0.0
+   * @category handlers
+   */
   <Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, const Name extends Endpoints["name"], E, R>(
     name: Name,
     handler: HttpApiEndpoint.HttpApiEndpoint.HandlerWithName<Endpoints, Name, E, R>
@@ -321,6 +345,12 @@ export const handle: {
     RG | HttpApiEndpoint.HttpApiEndpoint.ExcludeProvided<R>,
     HttpApiEndpoint.HttpApiEndpoint.ExcludeName<Endpoints, Name>
   >
+  /**
+   * Add the implementation for an `HttpApiEndpoint` to a `Handlers` group.
+   *
+   * @since 1.0.0
+   * @category handlers
+   */
   <Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, const Name extends Endpoints["name"], E, R>(
     name: Name,
     handler: HttpApiEndpoint.HttpApiEndpoint.HandlerResponseWithName<Endpoints, Name, E, R>,
@@ -436,18 +466,36 @@ const middlewareAddNoContext = (
  * @category middleware
  */
 export const middlewareLayer: {
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <EX = never, RX = never>(
     middleware: ApiMiddleware.Fn<never> | Effect.Effect<ApiMiddleware.Fn<never>, EX, RX>,
     options?: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, RX>
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <R, EX = never, RX = never>(
     middleware: ApiMiddleware.Fn<never, R> | Effect.Effect<ApiMiddleware.Fn<never, R>, EX, RX>,
     options: {
       readonly withContext: true
     }
   ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | RX>
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, EX = never, RX = never>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: ApiMiddleware.Fn<NoInfer<Error>> | Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>>, EX, RX>,
@@ -455,6 +503,12 @@ export const middlewareLayer: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, RX>
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, R, EX = never, RX = never>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: ApiMiddleware.Fn<NoInfer<Error>, R> | Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>, R>, EX, RX>,
@@ -493,18 +547,39 @@ export const middlewareLayer: {
  * @category middleware
  */
 export const middlewareLayerScoped: {
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <EX, RX>(
     middleware: Effect.Effect<ApiMiddleware.Fn<never>, EX, RX>,
     options?: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, Exclude<RX, Scope>>
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <R, EX, RX>(
     middleware: Effect.Effect<ApiMiddleware.Fn<never, R>, EX, RX>,
     options: {
       readonly withContext: true
     }
   ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | Exclude<RX, Scope>>
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, EX, RX>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>>, EX, RX>,
@@ -512,6 +587,13 @@ export const middlewareLayerScoped: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, Exclude<RX, Scope>>
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, R, EX, RX>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>, R>, EX, RX>,

package/src/HttpApiEndpoint.ts

@@ -444,6 +444,13 @@ export const del: <const Name extends string>(
  * @category result
  */
 export const setSuccess: {
+  /**
+   * Set the schema for the success response of the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 200.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <S extends Schema.Schema.Any>(
     schema: S,
     annotations?: {
@@ -461,6 +468,13 @@ export const setSuccess: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, _P, _H, Schema.Schema.Type<S>, _E, _R | Schema.Schema.Context<S>>
+  /**
+   * Set the schema for the success response of the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 200.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -513,6 +527,13 @@ export const setSuccess: {
  * @category result
  */
 export const addError: {
+  /**
+   * Add an error response schema to the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 500.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <E extends Schema.Schema.All>(
     schema: E,
     annotations?: {
@@ -530,6 +551,13 @@ export const addError: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E | Schema.Schema.Type<E>, _R | Schema.Schema.Context<E>>
+  /**
+   * Add an error response schema to the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 500.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -593,9 +621,20 @@ export const addError: {
  * @category request
  */
 export const setPayload: {
-  <Method extends HttpMethod, P extends Schema.Schema.All>(
-    schema: P & HttpApiEndpoint.ValidatePayload<Method, P>
-  ): <
+  /**
+   * Set the schema for the request body of the endpoint. The schema will be
+   * used to validate the request body before the handler is called.
+   *
+   * For endpoints with no request body, the payload will use the url search
+   * parameters.
+   *
+   * You can set a multipart schema to handle file uploads by using the
+   * `HttpApiSchema.Multipart` combinator.
+   *
+   * @since 1.0.0
+   * @category request
+   */
+  <Method extends HttpMethod, P extends Schema.Schema.All>(schema: P & HttpApiEndpoint.ValidatePayload<Method, P>): <
     Name extends string,
     _Path,
     _P,
@@ -606,6 +645,19 @@ export const setPayload: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, Schema.Schema.Type<P>, _H, _S, _E, _R | Schema.Schema.Context<P>>
+  /**
+   * Set the schema for the request body of the endpoint. The schema will be
+   * used to validate the request body before the handler is called.
+   *
+   * For endpoints with no request body, the payload will use the url search
+   * parameters.
+   *
+   * You can set a multipart schema to handle file uploads by using the
+   * `HttpApiSchema.Multipart` combinator.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -650,9 +702,14 @@ export const setPayload: {
  * @category request
  */
 export const setPath: {
-  <Path extends Schema.Schema.Any>(
-    schema: Path & HttpApiEndpoint.ValidatePath<Path>
-  ): <
+  /**
+   * Set the schema for the path parameters of the endpoint. The schema will be
+   * used to validate the path parameters before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
+  <Path extends Schema.Schema.Any>(schema: Path & HttpApiEndpoint.ValidatePath<Path>): <
     Name extends string,
     Method extends HttpMethod,
     _Path,
@@ -664,6 +721,13 @@ export const setPath: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, Schema.Schema.Type<Path>, _P, _H, _S, _E, _R | Schema.Schema.Context<Path>>
+  /**
+   * Set the schema for the path parameters of the endpoint. The schema will be
+   * used to validate the path parameters before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -708,9 +772,14 @@ export const setPath: {
  * @category request
  */
 export const setHeaders: {
-  <Method extends HttpMethod, H extends Schema.Schema.Any>(
-    schema: H & HttpApiEndpoint.ValidateHeaders<H>
-  ): <
+  /**
+   * Set the schema for the headers of the endpoint. The schema will be
+   * used to validate the headers before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
+  <Method extends HttpMethod, H extends Schema.Schema.Any>(schema: H & HttpApiEndpoint.ValidateHeaders<H>): <
     Name extends string,
     _Path,
     _P,
@@ -721,6 +790,13 @@ export const setHeaders: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, _P, Schema.Schema.Type<H>, _S, _E, _R | Schema.Schema.Context<H>>
+  /**
+   * Set the schema for the headers of the endpoint. The schema will be
+   * used to validate the headers before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -764,7 +840,19 @@ export const setHeaders: {
  * @category request
  */
 export const prefix: {
+  /**
+   * Add a prefix to the path of the endpoint.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   (prefix: HttpRouter.PathInput): <A extends HttpApiEndpoint.All>(self: A) => A
+  /**
+   * Add a prefix to the path of the endpoint.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <A extends HttpApiEndpoint.All>(self: A, prefix: HttpRouter.PathInput): A
 } = dual(2, <A extends HttpApiEndpoint.All>(self: A, prefix: HttpRouter.PathInput): A =>
   makeProto({
@@ -788,7 +876,19 @@ export const schemaSuccess = <A extends HttpApiEndpoint.All>(
  * @category annotations
  */
 export const annotateMerge: {
+  /**
+   * Merge the annotations of the endpoint with the provided context.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I>(context: Context.Context<I>): <A extends HttpApiEndpoint.All>(self: A) => A
+  /**
+   * Merge the annotations of the endpoint with the provided context.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiEndpoint.All, I>(self: A, context: Context.Context<I>): A
 } = dual(
   2,
@@ -806,7 +906,19 @@ export const annotateMerge: {
  * @category annotations
  */
 export const annotate: {
+  /**
+   * Add an annotation to the endpoint.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApiEndpoint.All>(self: A) => A
+  /**
+   * Add an annotation to the endpoint.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiEndpoint.All, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
 } = dual(
   3,

package/src/HttpApiGroup.ts

@@ -175,21 +175,30 @@ export const make = <Name extends string>(identifier: Name): HttpApiGroup<Name>
  * @category endpoints
  */
 export const add: {
+  /**
+   * Add an `HttpApiEndpoint` to an `HttpApiGroup`.
+   *
+   * @since 1.0.0
+   * @category endpoints
+   */
   <A extends HttpApiEndpoint.HttpApiEndpoint.All>(
     endpoint: A
   ): <Name extends string, Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, Error, ErrorR>(
     self: HttpApiGroup<Name, Endpoints, Error, ErrorR>
   ) => HttpApiGroup<Name, Endpoints | A, Error, ErrorR>
+  /**
+   * Add an `HttpApiEndpoint` to an `HttpApiGroup`.
+   *
+   * @since 1.0.0
+   * @category endpoints
+   */
   <
     Name extends string,
     Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All,
     Error,
     ErrorR,
     A extends HttpApiEndpoint.HttpApiEndpoint.All
-  >(
-    self: HttpApiGroup<Name, Endpoints, Error, ErrorR>,
-    endpoint: A
-  ): HttpApiGroup<Name, Endpoints | A, Error, ErrorR>
+  >(self: HttpApiGroup<Name, Endpoints, Error, ErrorR>, endpoint: A): HttpApiGroup<Name, Endpoints | A, Error, ErrorR>
 } = dual(2, <
   Name extends string,
   Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All,
@@ -215,6 +224,13 @@ export const add: {
  * @category errors
  */
 export const addError: {
+  /**
+   * Add an error schema to an `HttpApiGroup`, which is shared by all endpoints in the
+   * group.
+   *
+   * @since 1.0.0
+   * @category errors
+   */
   <A, I, R>(
     schema: Schema.Schema<A, I, R>,
     annotations?: {
@@ -223,6 +239,13 @@ export const addError: {
   ): <Name extends string, Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, Error, ErrorR>(
     self: HttpApiGroup<Name, Endpoints, Error, ErrorR>
   ) => HttpApiGroup<Name, Endpoints, Error | A, ErrorR | R>
+  /**
+   * Add an error schema to an `HttpApiGroup`, which is shared by all endpoints in the
+   * group.
+   *
+   * @since 1.0.0
+   * @category errors
+   */
   <Name extends string, Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, Error, ErrorR, A, I, R>(
     self: HttpApiGroup<Name, Endpoints, Error, ErrorR>,
     schema: Schema.Schema<A, I, R>,
@@ -260,11 +283,23 @@ export const addError: {
  * @category endpoints
  */
 export const prefix: {
-  (
-    prefix: PathInput
-  ): <Name extends string, Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, Error, ErrorR>(
+  /**
+   * Add a path prefix to all endpoints in an `HttpApiGroup`. Note that this will only
+   * add the prefix to the endpoints before this api is called.
+   *
+   * @since 1.0.0
+   * @category endpoints
+   */
+  (prefix: PathInput): <Name extends string, Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, Error, ErrorR>(
     self: HttpApiGroup<Name, Endpoints, Error, ErrorR>
   ) => HttpApiGroup<Name, Endpoints, Error, ErrorR>
+  /**
+   * Add a path prefix to all endpoints in an `HttpApiGroup`. Note that this will only
+   * add the prefix to the endpoints before this api is called.
+   *
+   * @since 1.0.0
+   * @category endpoints
+   */
   <Name extends string, Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, Error, ErrorR>(
     self: HttpApiGroup<Name, Endpoints, Error, ErrorR>,
     prefix: PathInput
@@ -287,7 +322,19 @@ export const prefix: {
  * @category annotations
  */
 export const annotateMerge: {
+  /**
+   * Merge the annotations of an `HttpApiGroup` with a new context.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I>(context: Context.Context<I>): <A extends HttpApiGroup.Any>(self: A) => A
+  /**
+   * Merge the annotations of an `HttpApiGroup` with a new context.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiGroup.Any, I>(self: A, context: Context.Context<I>): A
 } = dual(
   2,
@@ -305,7 +352,19 @@ export const annotateMerge: {
  * @category annotations
  */
 export const annotate: {
+  /**
+   * Add an annotation to an `HttpApiGroup`.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApiGroup.Any>(self: A) => A
+  /**
+   * Add an annotation to an `HttpApiGroup`.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiGroup.Any, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
 } = dual(
   3,
@@ -328,7 +387,25 @@ export const annotate: {
  * @category annotations
  */
 export const annotateEndpointsMerge: {
+  /**
+   * For each endpoint in an `HttpApiGroup`, update the annotations with a new
+   * context.
+   *
+   * Note that this will only update the annotations before this api is called.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I>(context: Context.Context<I>): <A extends HttpApiGroup.Any>(self: A) => A
+  /**
+   * For each endpoint in an `HttpApiGroup`, update the annotations with a new
+   * context.
+   *
+   * Note that this will only update the annotations before this api is called.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiGroup.Any, I>(self: A, context: Context.Context<I>): A
 } = dual(
   2,
@@ -351,7 +428,25 @@ export const annotateEndpointsMerge: {
  * @category annotations
  */
 export const annotateEndpoints: {
+  /**
+   * For each endpoint in an `HttpApiGroup`, add an annotation.
+   *
+   * Note that this will only add the annotation to the endpoints before this api
+   * is called.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApiGroup.Any>(self: A) => A
+  /**
+   * For each endpoint in an `HttpApiGroup`, add an annotation.
+   *
+   * Note that this will only add the annotation to the endpoints before this api
+   * is called.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiGroup.Any, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
 } = dual(
   3,