microsoft · Timothee Guerin (timotheeguerin) · Aug 4, 2026 · Aug 5, 2026
diff --git a/.chronus/changes/docs-http-2026-8-11.md b/.chronus/changes/docs-http-2026-8-11.md
@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http"
+---
+
+Add missing documentation to public declarations and fix the `@route` `@param` name
@@ -296,6 +296,11 @@ op update(@header ifMatch: string): void; // headerName: if-match
 
 #### `@multipartBody`
 
+Specify that the target property is the body of a multipart request or response.
+
+The property type must be a model or tuple whose members are all `HttpPart`, each describing one
+part of the payload.
+
 ```typespec
 @TypeSpec.Http.multipartBody
 ```
@@ -366,7 +371,7 @@ Explicitly specify that this property is to be interpolated as a path parameter.
 
 | Name               | Type                                          | Description                                                    |
 | ------------------ | --------------------------------------------- | -------------------------------------------------------------- |
-| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the uri template or options. |
+| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the URI template or options. |
 
 ##### Examples
 
@@ -460,9 +465,9 @@ Defines the relative route URI template for the target operation as defined by [
 
 ##### Parameters
 
-| Name | Type             | Description |
-| ---- | ---------------- | ----------- |
-| path | `valueof string` |             |
+| Name | Type             | Description                      |
+| ---- | ---------------- | -------------------------------- |
+| path | `valueof string` | URI template for this operation. |
 
 ##### Examples
 

@@ -134,7 +134,7 @@ export type QueryDecorator = (
 /**
  * Explicitly specify that this property is to be interpolated as a path parameter.
  *
- * @param paramNameOrOptions Optional name of the parameter in the uri template or options.
+ * @param paramNameOrOptions Optional name of the parameter in the URI template or options.
  * @example
  * ```typespec
  * @route("/read/{explicit}/things/{implicit}")
@@ -178,17 +178,19 @@ export type BodyIgnoreDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
+ * Specify that the target property is the body of a multipart request or response.
  *
- *
+ * The property type must be a model or tuple whose members are all `HttpPart`, each describing one
+ * part of the payload.
  *
  * @example
  * ```tsp
  * op upload(
  *   @header `content-type`: "multipart/form-data",
  *   @multipartBody body: {
- *     fullName: HttpPart<string>,
- *     headShots: HttpPart<Image>[]
- *   }
+ *     fullName: HttpPart<string>;
+ *     headShots: HttpPart<Image>[];
+ *   },
  * ): void;
  * ```
  */
@@ -348,7 +350,7 @@ export type UseAuthDecorator = (
  *
  * `@route` can only be applied to operations, namespaces, and interfaces.
  *
- * @param uriTemplate Uri template for this operation.
+ * @param path URI template for this operation.
  * @example Simple path parameter
  *
  * ```typespec

@@ -232,5 +232,6 @@ model OpenIdConnectAuth<ConnectUrl extends string, Scopes extends string[] = []>
  */
 @doc("")
 model NoAuth {
+  /** No authentication. */
   type: AuthType.noAuth;
 }
@@ -113,8 +113,11 @@ model QueryOptions {
  */
 extern dec query(target: ModelProperty, queryNameOrOptions?: valueof string | QueryOptions);
 
+/**
+ * Options for configuring how a path parameter is serialized into the URI template.
+ */
 model PathOptions {
-  /** Name of the parameter in the uri template. */
+  /** Name of the parameter in the URI template. */
   name?: string;
 
   /**
@@ -143,7 +146,7 @@ model PathOptions {
 /**
  * Explicitly specify that this property is to be interpolated as a path parameter.
  *
- * @param paramNameOrOptions Optional name of the parameter in the uri template or options.
+ * @param paramNameOrOptions Optional name of the parameter in the URI template or options.
  *
  * @example
  *
@@ -195,15 +198,20 @@ extern dec bodyRoot(target: ModelProperty);
 extern dec bodyIgnore(target: ModelProperty);
 
 /**
+ * Specify that the target property is the body of a multipart request or response.
+ *
+ * The property type must be a model or tuple whose members are all `HttpPart`, each describing one
+ * part of the payload.
+ *
  * @example
  *
  * ```tsp
  * op upload(
  *   @header `content-type`: "multipart/form-data",
  *   @multipartBody body: {
- *     fullName: HttpPart<string>,
- *     headShots: HttpPart<Image>[]
- *   }
+ *     fullName: HttpPart<string>;
+ *     headShots: HttpPart<Image>[];
+ *   },
  * ): void;
  * ```
  */
@@ -267,11 +275,11 @@ model PatchOptions {
    * If set to `false`, disables the implicit transform that makes the body of a
    * PATCH operation deeply optional.
    *
-   * @deprecated `implicitOptionality` is deprecated and will be removed.
-   *   To preserve the previous behavior, define and use an explicit patch model
-   *   with optional properties for your `@body` parameter.
-   *   For actual JSON Merge Patch behavior, use `MergePatchUpdate<T>` as the
-   *   `@body` type (for example: `@patch op update(@body pet: MergePatchUpdate<Pet>): void;`).
+   * **Deprecated:** `implicitOptionality` is deprecated and will be removed.
+   * To preserve the previous behavior, define and use an explicit patch model
+   * with optional properties for your `@body` parameter.
+   * For actual JSON Merge Patch behavior, use `MergePatchUpdate<T>` as the
+   * `@body` type (for example: `@patch op update(@body pet: MergePatchUpdate<Pet>): void;`).
    */
   implicitOptionality?: boolean;
 }
@@ -384,7 +392,7 @@ extern dec useAuth(target: Namespace | Interface | Operation, auth: {} | Union |
  *
  * `@route` can only be applied to operations, namespaces, and interfaces.
  *
- * @param uriTemplate Uri template for this operation.
+ * @param path URI template for this operation.
  *
  * @example Simple path parameter
  *

@@ -256,20 +256,55 @@ model File<ContentType extends string = string, Contents extends bytes | string
   contents: Contents;
 }
 
+/**
+ * Options for configuring an individual part of a multipart payload.
+ */
 model HttpPartOptions {
   /** Name of the part when using the array form. */
   name?: string;
 }
 
+/**
+ * Represents a single part of a multipart payload.
+ *
+ * @template Type The type of the part's content.
+ * @template Options Options for this part, such as the name to use when the part is repeated.
+ *
+ * @example
+ *
+ * ```typespec
+ * op upload(
+ *   @header `content-type`: "multipart/form-data",
+ *   @multipartBody body: {
+ *     fullName: HttpPart<string>;
+ *     headShots: HttpPart<Image>[];
+ *   },
+ * ): void;
+ * ```
+ */
 @Private.httpPart(Type, Options)
 model HttpPart<Type, Options extends valueof HttpPartOptions = #{}> {}
 
+/**
+ * Describes a web link as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288).
+ */
 model Link {
+  /** The target URI of the link. */
   target: url;
+
+  /** The relation type of the link, describing how the target relates to the current resource. */
   rel: string;
+
+  /** Additional target attributes to serialize as link parameters. */
   attributes?: Record<unknown>;
 }
 
+/**
+ * A `Link` header value as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288).
+ *
+ * @template T The links carried by the header, either as a map of relation type to URI or as a
+ * list of `Link`.
+ */
 scalar LinkHeader<T extends Record<url> | Link[]> extends string;
 
 /**

@@ -370,23 +370,39 @@ model TypeSpec.Http.HeaderOptions
 
 ### `HttpPart` {#TypeSpec.Http.HttpPart}
 
+Represents a single part of a multipart payload.
+
 ```typespec
 model TypeSpec.Http.HttpPart<Type, Options>
 ```
 
 #### Template Parameters
 
-| Name    | Description |
-| ------- | ----------- |
-| Type    |             |
-| Options |             |
+| Name    | Description                                                               |
+| ------- | ------------------------------------------------------------------------- |
+| Type    | The type of the part's content.                                           |
+| Options | Options for this part, such as the name to use when the part is repeated. |
+
+#### Examples
+
+```typespec
+op upload(
+  @header `content-type`: "multipart/form-data",
+  @multipartBody body: {
+    fullName: HttpPart<string>;
+    headShots: HttpPart<Image>[];
+  },
+): void;
+```
 
 #### Properties
 
 None
 
 ### `HttpPartOptions` {#TypeSpec.Http.HttpPartOptions}
 
+Options for configuring an individual part of a multipart payload.
+
 ```typespec
 model TypeSpec.Http.HttpPartOptions
 ```
@@ -416,17 +432,19 @@ model TypeSpec.Http.ImplicitFlow
 
 ### `Link` {#TypeSpec.Http.Link}
 
+Describes a web link as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288).
+
 ```typespec
 model TypeSpec.Http.Link
 ```
 
 #### Properties
 
-| Name        | Type              | Description |
-| ----------- | ----------------- | ----------- |
-| target      | `url`             |             |
-| rel         | `string`          |             |
-| attributes? | `Record<unknown>` |             |
+| Name        | Type              | Description                                                                               |
+| ----------- | ----------------- | ----------------------------------------------------------------------------------------- |
+| target      | `url`             | The target URI of the link.                                                               |
+| rel         | `string`          | The relation type of the link, describing how the target relates to the current resource. |
+| attributes? | `Record<unknown>` | Additional target attributes to serialize as link parameters.                             |
 
 ### `LocationHeader` {#TypeSpec.Http.LocationHeader}
 
@@ -468,9 +486,9 @@ model TypeSpec.Http.NoAuth
 
 #### Properties
 
-| Name | Type                            | Description |
-| ---- | ------------------------------- | ----------- |
-| type | `TypeSpec.Http.AuthType.noAuth` |             |
+| Name | Type                            | Description        |
+| ---- | ------------------------------- | ------------------ |
+| type | `TypeSpec.Http.AuthType.noAuth` | No authentication. |
 
 ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse}
 
@@ -612,12 +630,14 @@ model TypeSpec.Http.PatchOptions
 
 #### Properties
 
-| Name                 | Type      | Description                                                                                                       |
-| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
-| implicitOptionality? | `boolean` | If set to `false`, disables the implicit transform that makes the body of a<br />PATCH operation deeply optional. |
+| Name                 | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| implicitOptionality? | `boolean` | If set to `false`, disables the implicit transform that makes the body of a<br />PATCH operation deeply optional.<br /><br />**Deprecated:** `implicitOptionality` is deprecated and will be removed.<br />To preserve the previous behavior, define and use an explicit patch model<br />with optional properties for your `@body` parameter.<br />For actual JSON Merge Patch behavior, use `MergePatchUpdate<T>` as the<br />`@body` type (for example: `@patch op update(@body pet: MergePatchUpdate<Pet>): void;`). |
 
 ### `PathOptions` {#TypeSpec.Http.PathOptions}
 
+Options for configuring how a path parameter is serialized into the URI template.
+
 ```typespec
 model TypeSpec.Http.PathOptions
 ```
@@ -626,7 +646,7 @@ model TypeSpec.Http.PathOptions
 
 | Name           | Type                                                      | Description                                                                                                                                                                                                                                  |
 | -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| name?          | `string`                                                  | Name of the parameter in the uri template.                                                                                                                                                                                                   |
+| name?          | `string`                                                  | Name of the parameter in the URI template.                                                                                                                                                                                                   |
 | explode?       | `boolean`                                                 | When interpolating this parameter in the case of array or object expand each value using the given style.<br />Equivalent of adding `*` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) |
 | style?         | `"simple" \| "label" \| "matrix" \| "fragment" \| "path"` | Different interpolating styles for the path parameter.<br />- `simple`: No special encoding.<br />- `label`: Using `.` separator.<br />- `matrix`: `;` as separator.<br />- `fragment`: `#` as separator.<br />- `path`: `/` as separator.   |
 | allowReserved? | `boolean`                                                 | When interpolating this parameter do not encode reserved characters.<br />Equivalent of adding `+` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)                                      |
@@ -746,6 +766,8 @@ enum TypeSpec.Http.OAuth2FlowType
 
 ### `LinkHeader` {#TypeSpec.Http.LinkHeader}
 
+A `Link` header value as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288).
+
 ```typespec
 scalar TypeSpec.Http.LinkHeader
 ```
@@ -250,6 +250,11 @@ op update(@header ifMatch: string): void; // headerName: if-match
 
 ### `@multipartBody` {#@TypeSpec.Http.multipartBody}
 
+Specify that the target property is the body of a multipart request or response.
+
+The property type must be a model or tuple whose members are all `HttpPart`, each describing one
+part of the payload.
+
 ```typespec
 @TypeSpec.Http.multipartBody
 ```
@@ -320,7 +325,7 @@ Explicitly specify that this property is to be interpolated as a path parameter.
 
 | Name               | Type                                          | Description                                                    |
 | ------------------ | --------------------------------------------- | -------------------------------------------------------------- |
-| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the uri template or options. |
+| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the URI template or options. |
 
 #### Examples
 
@@ -414,9 +419,9 @@ Defines the relative route URI template for the target operation as defined by [
 
 #### Parameters
 
-| Name | Type             | Description |
-| ---- | ---------------- | ----------- |
-| path | `valueof string` |             |
+| Name | Type             | Description                      |
+| ---- | ---------------- | -------------------------------- |
+| path | `valueof string` | URI template for this operation. |
 
 #### Examples