diff --git a/.chronus/changes/docs-events-2026-8-11.md b/.chronus/changes/docs-events-2026-8-11.md new file mode 100644 index 00000000000..d2ad747d05b --- /dev/null +++ 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 new file mode 100644 index 00000000000..583425ac819 --- /dev/null +++ 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 new file mode 100644 index 00000000000..37ffcd2111e --- /dev/null +++ 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 new file mode 100644 index 00000000000..bccc6663731 --- /dev/null +++ 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 diff --git a/packages/events/README.md b/packages/events/README.md index 144249df7f0..06b86ef9212 100644 --- a/packages/events/README.md +++ b/packages/events/README.md @@ -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 diff --git a/packages/events/generated-defs/TypeSpec.Events.ts b/packages/events/generated-defs/TypeSpec.Events.ts index 7a4e9bf094d..9961b6fb9e6 100644 --- a/packages/events/generated-defs/TypeSpec.Events.ts +++ b/packages/events/generated-defs/TypeSpec.Events.ts @@ -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, diff --git a/packages/events/lib/decorators.tsp b/packages/events/lib/decorators.tsp index a216bd869b1..4d6cf712c27 100644 --- a/packages/events/lib/decorators.tsp +++ b/packages/events/lib/decorators.tsp @@ -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); diff --git a/packages/graphql/README.md b/packages/graphql/README.md index 09b5a8dc94c..007979ec71e 100644 --- a/packages/graphql/README.md +++ b/packages/graphql/README.md @@ -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 diff --git a/packages/graphql/generated-defs/TypeSpec.GraphQL.ts b/packages/graphql/generated-defs/TypeSpec.GraphQL.ts index 16ea56e7827..c854d6aa9f0 100644 --- a/packages/graphql/generated-defs/TypeSpec.GraphQL.ts +++ b/packages/graphql/generated-defs/TypeSpec.GraphQL.ts @@ -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, diff --git a/packages/graphql/lib/interface.tsp b/packages/graphql/lib/interface.tsp index 081e06b0a8e..3e4be6bb46f 100644 --- a/packages/graphql/lib/interface.tsp +++ b/packages/graphql/lib/interface.tsp @@ -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[]); diff --git a/packages/graphql/lib/operation-fields.tsp b/packages/graphql/lib/operation-fields.tsp index 8c918e7edcf..ace5f0d7f8d 100644 --- a/packages/graphql/lib/operation-fields.tsp +++ b/packages/graphql/lib/operation-fields.tsp @@ -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[]); diff --git a/packages/graphql/lib/schema.tsp b/packages/graphql/lib/schema.tsp index 7e815e534d3..993b6931a9b 100644 --- a/packages/graphql/lib/schema.tsp +++ b/packages/graphql/lib/schema.tsp @@ -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); diff --git a/packages/graphql/package.json b/packages/graphql/package.json index 81f20aa0789..69960f378a6 100644 --- a/packages/graphql/package.json +++ b/packages/graphql/package.json @@ -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:", diff --git a/packages/http-client/generated-defs/TypeSpec.HttpClient.ts b/packages/http-client/generated-defs/TypeSpec.HttpClient.ts index 15824d985f4..9e5f21202e3 100644 --- a/packages/http-client/generated-defs/TypeSpec.HttpClient.ts +++ b/packages/http-client/generated-defs/TypeSpec.HttpClient.ts @@ -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, diff --git a/packages/http-client/lib/common.tsp b/packages/http-client/lib/common.tsp index 32e10019630..709d5c502d4 100644 --- a/packages/http-client/lib/common.tsp +++ b/packages/http-client/lib/common.tsp @@ -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; } diff --git a/packages/http-client/lib/decorators.tsp b/packages/http-client/lib/decorators.tsp index ae7b01da535..3e3b9a5396c 100644 --- a/packages/http-client/lib/decorators.tsp +++ b/packages/http-client/lib/decorators.tsp @@ -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); diff --git a/packages/protobuf/README.md b/packages/protobuf/README.md index 01afd6f837b..1e407639097 100644 --- a/packages/protobuf/README.md +++ b/packages/protobuf/README.md @@ -74,7 +74,17 @@ The field index of a Protobuf message must: - fall between 1 and 229 - 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) diff --git a/packages/protobuf/generated-defs/TypeSpec.Protobuf.ts b/packages/protobuf/generated-defs/TypeSpec.Protobuf.ts index a0a5160e184..5b4a5666840 100644 --- a/packages/protobuf/generated-defs/TypeSpec.Protobuf.ts +++ b/packages/protobuf/generated-defs/TypeSpec.Protobuf.ts @@ -30,9 +30,7 @@ export type MessageDecorator = ( * The field index of a Protobuf message must: * - fall between 1 and 229 - 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 diff --git a/packages/protobuf/lib/proto.tsp b/packages/protobuf/lib/proto.tsp index d9f37dd3aa0..149d8b06928 100644 --- a/packages/protobuf/lib/proto.tsp +++ b/packages/protobuf/lib/proto.tsp @@ -27,9 +27,11 @@ namespace TypeSpec.Protobuf; */ @Private.externRef(Path, Name) model Extern { - // 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 229 - 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 { /** diff --git a/packages/protobuf/package.json b/packages/protobuf/package.json index ec95d6e351b..3e8ed2d0272 100644 --- a/packages/protobuf/package.json +++ b/packages/protobuf/package.json @@ -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:", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 538087e90a2..a80f5650218 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -960,6 +960,9 @@ importers: '@typespec/http': specifier: workspace:~ version: link:../http + '@typespec/library-linter': + specifier: workspace:^ + version: link:../library-linter '@typespec/mutator-framework': specifier: workspace:~ version: link:../mutator-framework @@ -2084,6 +2087,9 @@ importers: '@typespec/compiler': specifier: workspace:^ version: link:../compiler + '@typespec/library-linter': + specifier: workspace:^ + version: link:../library-linter '@typespec/tspd': specifier: workspace:^ version: link:../tspd diff --git a/website/src/content/docs/docs/emitters/graphql/reference/decorators.md b/website/src/content/docs/docs/emitters/graphql/reference/decorators.md index fab456d9212..7dec784a998 100644 --- a/website/src/content/docs/docs/emitters/graphql/reference/decorators.md +++ b/website/src/content/docs/docs/emitters/graphql/reference/decorators.md @@ -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 diff --git a/website/src/content/docs/docs/emitters/protobuf/reference/data-types.md b/website/src/content/docs/docs/emitters/protobuf/reference/data-types.md index 21b5a0fa21e..b5b17fe2211 100644 --- a/website/src/content/docs/docs/emitters/protobuf/reference/data-types.md +++ b/website/src/content/docs/docs/emitters/protobuf/reference/data-types.md @@ -40,9 +40,9 @@ model Widget is Extern<"path/to/test.proto", "test.Widget">; #### Properties -| Name | Type | Description | -| ------- | ------- | ----------- | -| _extern | `never` | | +| Name | Type | Description | +| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _extern | `never` | 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. | ### `Map` {#TypeSpec.Protobuf.Map} @@ -69,7 +69,7 @@ None ### `PackageDetails` {#TypeSpec.Protobuf.PackageDetails} -Details applied to a package definition by the [`@package`](./decorators# +Details applied to a package definition by the [`@package`](./decorators#%40TypeSpec.Protobuf.package) decorator. ```typespec model TypeSpec.Protobuf.PackageDetails @@ -91,7 +91,7 @@ The streaming mode of an operation. One of: - `Out`: the output of the operation is streaming. - `None`: neither the input nor the output are streaming. -See the [`@stream`](./decorators# +See the [`@stream`](./decorators#%40TypeSpec.Protobuf.stream) decorator. ```typespec enum TypeSpec.Protobuf.StreamMode @@ -190,9 +190,9 @@ model TypeSpec.Protobuf.WellKnown.Any #### Properties -| Name | Type | Description | -| ------- | ------- | ----------- | -| _extern | `never` | | +| Name | Type | Description | +| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _extern | `never` | 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. | ### `Empty` {#TypeSpec.Protobuf.WellKnown.Empty} @@ -206,9 +206,9 @@ model TypeSpec.Protobuf.WellKnown.Empty #### Properties -| Name | Type | Description | -| ------- | ------- | ----------- | -| _extern | `never` | | +| Name | Type | Description | +| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _extern | `never` | 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. | ### `LatLng` {#TypeSpec.Protobuf.WellKnown.LatLng} @@ -222,9 +222,9 @@ model TypeSpec.Protobuf.WellKnown.LatLng #### Properties -| Name | Type | Description | -| ------- | ------- | ----------- | -| _extern | `never` | | +| Name | Type | Description | +| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _extern | `never` | 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. | ### `Timestamp` {#TypeSpec.Protobuf.WellKnown.Timestamp} @@ -238,6 +238,6 @@ model TypeSpec.Protobuf.WellKnown.Timestamp #### Properties -| Name | Type | Description | -| ------- | ------- | ----------- | -| _extern | `never` | | +| Name | Type | Description | +| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _extern | `never` | 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. | diff --git a/website/src/content/docs/docs/emitters/protobuf/reference/decorators.md b/website/src/content/docs/docs/emitters/protobuf/reference/decorators.md index cdbd04a4fcb..5ae4ea089f3 100644 --- a/website/src/content/docs/docs/emitters/protobuf/reference/decorators.md +++ b/website/src/content/docs/docs/emitters/protobuf/reference/decorators.md @@ -17,7 +17,17 @@ The field index of a Protobuf message must: - fall between 1 and 229 - 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) diff --git a/website/src/content/docs/docs/libraries/events/reference/decorators.md b/website/src/content/docs/docs/libraries/events/reference/decorators.md index 1df2148655d..91897cff8a4 100644 --- a/website/src/content/docs/docs/libraries/events/reference/decorators.md +++ b/website/src/content/docs/docs/libraries/events/reference/decorators.md @@ -24,9 +24,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