microsoft · timotheeguerin · Aug 4, 2026
diff --git a/.chronus/changes/docs-events-2026-8-11.md b/.chronus/changes/docs-events-2026-8-11.md
@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/events"
+---
+
+Add missing documentation on public declarations and members
diff --git a/.chronus/changes/docs-graphql-2026-8-11.md b/.chronus/changes/docs-graphql-2026-8-11.md
@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/graphql"
+---
+
+Add missing documentation on public declarations and members
diff --git a/.chronus/changes/docs-http-client-2026-8-11.md b/.chronus/changes/docs-http-client-2026-8-11.md
@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http-client"
+---
+
+Add missing documentation on public declarations and members
diff --git a/.chronus/changes/docs-protobuf-2026-8-11.md b/.chronus/changes/docs-protobuf-2026-8-11.md
@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/protobuf"
+---
+
+Add missing documentation on public declarations and members
@@ -32,9 +32,9 @@ decorator.
 
 ##### Parameters
 
-| Name        | Type             | Description |
-| ----------- | ---------------- | ----------- |
-| contentType | `valueof string` |             |
+| Name        | Type             | Description                                     |
+| ----------- | ---------------- | ----------------------------------------------- |
+| contentType | `valueof string` | The content type of the event or event payload. |
 
 ##### Examples
 

@@ -45,6 +45,7 @@ export type EventsDecorator = (
  *   { done: false, @data @contentType("text/plain") value: string,}
  * }
  * ```
+ * @param contentType The content type of the event or event payload.
  */
 export type ContentTypeDecorator = (
   context: DecoratorContext,

@@ -41,6 +41,8 @@ extern dec events(target: Union);
  *   { done: false, @data @contentType("text/plain") value: string,}
  * }
  * ```
+ *
+ * @param contentType The content type of the event or event payload.
  */
 extern dec contentType(target: UnionVariant | ModelProperty, contentType: valueof string);
 

@@ -107,9 +107,9 @@ and all of the interfaces' properties must be present and compatible.
 
 ##### Parameters
 
-| Name       | Type      | Description |
-| ---------- | --------- | ----------- |
-| interfaces | `Model[]` |             |
+| Name       | Type      | Description                                                                 |
+| ---------- | --------- | --------------------------------------------------------------------------- |
+| interfaces | `Model[]` | The models to compose into the target, each emitted as a GraphQL interface. |
 
 ##### Examples
 
@@ -199,9 +199,9 @@ The operations become fields on the GraphQL type with their parameters as argume
 
 ##### Parameters
 
-| Name       | Type                       | Description |
-| ---------- | -------------------------- | ----------- |
-| operations | `Operation \| Interface[]` |             |
+| Name       | Type                       | Description                                                                  |
+| ---------- | -------------------------- | ---------------------------------------------------------------------------- |
+| operations | `Operation \| Interface[]` | The operations, or interfaces of operations, to add to the target as fields. |
 
 ##### Examples
 
@@ -252,9 +252,9 @@ All types and operations within the namespace will be emitted to a single GraphQ
 
 ##### Parameters
 
-| Name    | Type                                      | Description |
-| ------- | ----------------------------------------- | ----------- |
-| options | [valueof `SchemaOptions`](#schemaoptions) |             |
+| Name    | Type                                      | Description                               |
+| ------- | ----------------------------------------- | ----------------------------------------- |
+| options | [valueof `SchemaOptions`](#schemaoptions) | Options for the schema, such as its name. |
 
 ##### Examples
 

@@ -66,6 +66,7 @@ export type GraphqlInterfaceDecorator = (
  *   name: string;
  * }
  * ```
+ * @param interfaces The models to compose into the target, each emitted as a GraphQL interface.
  */
 export type ComposeDecorator = (
   context: DecoratorContext,
@@ -87,6 +88,7 @@ export type ComposeDecorator = (
  * }
  * // Emits: type Person { name: String!; followers(query: String!): [Person!]! }
  * ```
+ * @param operations The operations, or interfaces of operations, to add to the target as fields.
  */
 export type OperationFieldsDecorator = (
   context: DecoratorContext,
@@ -146,6 +148,7 @@ export type SubscriptionDecorator = (
  * }
  * // Emits: MyAPI.graphql
  * ```
+ * @param options Options for the schema, such as its name.
  */
 export type SchemaDecorator = (
   context: DecoratorContext,

@@ -53,5 +53,7 @@ extern dec graphqlInterface(
  *   name: string;
  * }
  * ```
+ *
+ * @param interfaces The models to compose into the target, each emitted as a GraphQL interface.
  */
 extern dec compose(target: Model, ...interfaces: Model[]);
@@ -19,5 +19,7 @@ alias OperationOrInterface = Operation | Interface;
  * }
  * // Emits: type Person { name: String!; followers(query: String!): [Person!]! }
  * ```
+ *
+ * @param operations The operations, or interfaces of operations, to add to the target as fields.
  */
 extern dec operationFields(target: Model, ...operations: OperationOrInterface[]);
@@ -27,5 +27,7 @@ namespace Schema {
  * }
  * // Emits: MyAPI.graphql
  * ```
+ *
+ * @param options Options for the schema, such as its name.
  */
 extern dec schema(target: Namespace, options?: valueof Schema.SchemaOptions);
@@ -38,7 +38,8 @@
   },
   "scripts": {
     "clean": "rimraf ./dist ./temp",
-    "build": "pnpm gen-extern-signature && alloy build",
+    "build": "pnpm gen-extern-signature && alloy build && pnpm lint-typespec-library",
+    "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
     "watch": "alloy build --watch",
     "gen-extern-signature": "tspd --enable-experimental gen-extern-signature .",
     "test": "vitest run",
@@ -66,6 +67,7 @@
     "@typespec/compiler": "workspace:~",
     "@typespec/emitter-framework": "workspace:~",
     "@typespec/http": "workspace:~",
+    "@typespec/library-linter": "workspace:^",
     "@typespec/mutator-framework": "workspace:~",
     "@typespec/tspd": "workspace:~",
     "rimraf": "catalog:",

@@ -4,6 +4,11 @@ export interface FeatureLifecycleOptions {
   readonly emitterScope?: string;
 }
 
+/**
+ * Mark a type or member as experimental, so generated clients can surface it as such.
+ *
+ * @param options Options for this decorator, such as the emitters it applies to.
+ */
 export type ExperimentalDecorator = (
   context: DecoratorContext,
   target: Type,

@@ -5,5 +5,6 @@ namespace TypeSpec.HttpClient;
  * You can use ”!” to exclude specific emitters, for example: `!@typespec/http-client-js, !@typespec/http-client-csharp`
  */
 model ClientDecoratorOptions {
+  /** Comma separated list of emitter names the decorator applies to. */
   emitterScope?: string;
 }
@@ -3,8 +3,16 @@ import "../dist/src/tsp-index.js";
 
 namespace TypeSpec.HttpClient;
 
+/**
+ * Options describing where a feature lifecycle decorator such as `@experimental` applies.
+ */
 model FeatureLifecycleOptions {
   ...ClientDecoratorOptions;
 }
 
+/**
+ * Mark a type or member as experimental, so generated clients can surface it as such.
+ *
+ * @param options Options for this decorator, such as the emitters it applies to.
+ */
 extern dec experimental(target: unknown, options?: valueof FeatureLifecycleOptions);
@@ -74,7 +74,17 @@ The field index of a Protobuf message must:
 
 - fall between 1 and 2<sup>29</sup> - 1, inclusive.
 - not fall within the implementation reserved range of 19000 to 19999, inclusive.
-- not fall within any range that was [marked reserved](#
+- not fall within any range that was [marked reserved](#%40TypeSpec.Protobuf.reserve).
+
+#### API Compatibility Note
+
+Fields are accessed by index, so changing the index of a field is an API breaking change.
+
+#### Encoding
+
+Field indices between 1 and 15 are encoded using a single byte, while field indices from 16 through 2047 require two
+bytes, so those indices between 1 and 15 should be preferred and reserved for elements that are frequently or always
+set in the message. See the [Protobuf binary format](https://protobuf.dev/programming-guides/encoding/).
 
 ```typespec
 @TypeSpec.Protobuf.field(index: valueof uint32)

@@ -30,9 +30,7 @@ export type MessageDecorator = (
  * The field index of a Protobuf message must:
  * - fall between 1 and 2<sup>29</sup> - 1, inclusive.
  * - not fall within the implementation reserved range of 19000 to 19999, inclusive.
- * - not fall within any range that was [marked reserved](#
- *
- * @TypeSpec .Protobuf.reserve).
+ * - not fall within any range that was [marked reserved](#%40TypeSpec.Protobuf.reserve).
  *
  * #### API Compatibility Note
  *
@@ -43,6 +41,7 @@ export type MessageDecorator = (
  * Field indices between 1 and 15 are encoded using a single byte, while field indices from 16 through 2047 require two
  * bytes, so those indices between 1 and 15 should be preferred and reserved for elements that are frequently or always
  * set in the message. See the [Protobuf binary format](https://protobuf.dev/programming-guides/encoding/).
+ *
  * @param index The whole-number index of the field.
  * @example
  * ```typespec

@@ -27,9 +27,11 @@ namespace TypeSpec.Protobuf;
  */
 @Private.externRef(Path, Name)
 model Extern<Path extends string, Name extends string> {
-  // This _extern property is needed so that getEffectiveModelType will have something to look up. Without it, if an
-  // Extern model is spread into the parameter of an operation, the resulting model is empty and carries no information
-  // that can relate it back to its original definition.
+  /**
+   * Never present. This property exists only so that `getEffectiveModelType` has something to look
+   * up: without it, an `Extern` model spread into an operation parameter yields an empty model that
+   * cannot be related back to its original definition.
+   */
   _extern: never;
 }
 
@@ -157,7 +159,7 @@ extern dec message(target: {});
  * The field index of a Protobuf message must:
  *   - fall between 1 and 2<sup>29</sup> - 1, inclusive.
  *   - not fall within the implementation reserved range of 19000 to 19999, inclusive.
- *   - not fall within any range that was [marked reserved](#@TypeSpec.Protobuf.reserve).
+ *   - not fall within any range that was [marked reserved](#%40TypeSpec.Protobuf.reserve).
  *
  * #### API Compatibility Note
  *
@@ -226,7 +228,7 @@ extern dec service(target: TypeSpec.Reflection.Interface);
 
 // FIXME: cannot link to the package decorator directly because it is detected as a broken link.
 /**
- * Details applied to a package definition by the [`@package`](./decorators#@TypeSpec.Protobuf.package) decorator.
+ * Details applied to a package definition by the [`@package`](./decorators#%40TypeSpec.Protobuf.package) decorator.
  */
 model PackageDetails {
   /**
@@ -262,7 +264,7 @@ extern dec `package`(target: TypeSpec.Reflection.Namespace, details?: PackageDet
  * - `Out`: the output of the operation is streaming.
  * - `None`: neither the input nor the output are streaming.
  *
- * See the [`@stream`](./decorators#@TypeSpec.Protobuf.stream) decorator.
+ * See the [`@stream`](./decorators#%40TypeSpec.Protobuf.stream) decorator.
  */
 enum StreamMode {
   /**

@@ -31,7 +31,8 @@
   "tspMain": "lib/proto.tsp",
   "scripts": {
     "clean": "rimraf ./dist ./temp",
-    "build": "pnpm gen-extern-signature && tsc -p tsconfig.build.json",
+    "build": "pnpm gen-extern-signature && tsc -p tsconfig.build.json && pnpm lint-typespec-library",
+    "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
     "watch": "tsc -p tsconfig.build.json --watch",
     "gen-extern-signature": "tspd --enable-experimental gen-extern-signature .",
     "test": "vitest run",
@@ -47,6 +48,7 @@
     "@types/micromatch": "catalog:",
     "@types/node": "catalog:",
     "@typespec/compiler": "workspace:^",
+    "@typespec/library-linter": "workspace:^",
     "@typespec/tspd": "workspace:^",
     "@vitest/coverage-v8": "catalog:",
     "@vitest/ui": "catalog:",

@@ -23,9 +23,9 @@ and all of the interfaces' properties must be present and compatible.
 
 #### Parameters
 
-| Name       | Type      | Description |
-| ---------- | --------- | ----------- |
-| interfaces | `Model[]` |             |
+| Name       | Type      | Description                                                                 |
+| ---------- | --------- | --------------------------------------------------------------------------- |
+| interfaces | `Model[]` | The models to compose into the target, each emitted as a GraphQL interface. |
 
 #### Examples
 
@@ -115,9 +115,9 @@ The operations become fields on the GraphQL type with their parameters as argume
 
 #### Parameters
 
-| Name       | Type                       | Description |
-| ---------- | -------------------------- | ----------- |
-| operations | `Operation \| Interface[]` |             |
+| Name       | Type                       | Description                                                                  |
+| ---------- | -------------------------- | ---------------------------------------------------------------------------- |
+| operations | `Operation \| Interface[]` | The operations, or interfaces of operations, to add to the target as fields. |
 
 #### Examples
 
@@ -168,9 +168,9 @@ All types and operations within the namespace will be emitted to a single GraphQ
 
 #### Parameters
 
-| Name    | Type                                                                             | Description |
-| ------- | -------------------------------------------------------------------------------- | ----------- |
-| options | [valueof `SchemaOptions`](./data-types.md#TypeSpec.GraphQL.Schema.SchemaOptions) |             |
+| Name    | Type                                                                             | Description                               |
+| ------- | -------------------------------------------------------------------------------- | ----------------------------------------- |
+| options | [valueof `SchemaOptions`](./data-types.md#TypeSpec.GraphQL.Schema.SchemaOptions) | Options for the schema, such as its name. |
 
 #### Examples
-Original file line number
+Diff line change
@@ Expand Up / @@ -41,6 +41,8 @@ extern dec events(target: Union); @@
      *   { done: false, @data @contentType("text/plain") value: string,}
      * }
      * ```
+     *
+     * @param contentType The content type of the event or event payload.
      */
     extern dec contentType(target: UnionVariant | ModelProperty, contentType: valueof string);
@@ Expand Down @@