[tcgc] add doc and summary to tcgc types

.chronus/changes/add_typespec_raw_doc-2024-7-15-16-7-32.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+add `doc` and `summary` to tcgc types

packages/typespec-client-generator-core/src/http.ts

@@ -4,6 +4,8 @@ import {
   Operation,
   Type,
   createDiagnosticCollector,
+  getDoc,
+  getSummary,
   ignoreDiagnostics,
   isErrorModel,
 } from "@typespec/compiler";
@@ -163,6 +165,8 @@ function getSdkHttpParameters(
         isGeneratedName: true,
         description: getDocHelper(context, tspBody.type).description,
         details: getDocHelper(context, tspBody.type).details,
+        doc: getDoc(context.program, tspBody.type),
+        summary: getSummary(context.program, tspBody.type),
         onClient: false,
         contentTypes: [],
         defaultContentType: "application/json", // actual content type info is added later
@@ -192,6 +196,7 @@ function getSdkHttpParameters(
     const contentTypeBase = {
       ...createContentTypeOrAcceptHeader(context, httpOperation, retval.bodyParam),
       description: `Body parameter's content type. Known values are ${retval.bodyParam.contentTypes}`,
+      doc: `Body parameter's content type. Known values are ${retval.bodyParam.contentTypes}`,
     };
     if (!methodParameters.some((m) => m.name === "contentType")) {
       methodParameters.push({
@@ -412,6 +417,8 @@ function getSdkHttpResponseAndExceptions(
           __raw: header,
           description: getDocHelper(context, header).description,
           details: getDocHelper(context, header).details,
+          doc: getDoc(context.program, header),
+          summary: getSummary(context.program, header),
           serializedName: getHeaderFieldName(context.program, header),
           type: clientType,
         });

packages/typespec-client-generator-core/src/interfaces.ts

@@ -98,8 +98,16 @@ export interface SdkClientType<TServiceOperation extends SdkServiceOperation>
   extends DecoratedType {
   kind: "client";
   name: string;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   description?: string;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   details?: string;
+  doc?: string;
+  summary?: string;
   initialization: SdkInitializationType;
   methods: SdkMethod<TServiceOperation>[];
   apiVersions: string[];
@@ -138,8 +146,16 @@ interface SdkTypeBase extends DecoratedType {
   __raw?: Type;
   kind: string;
   deprecation?: string;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   description?: string;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   details?: string;
+  doc?: string;
+  summary?: string;
 }
 
 export type SdkType =
@@ -410,8 +426,16 @@ export interface SdkModelPropertyTypeBase extends DecoratedType {
   type: SdkType;
   name: string;
   isGeneratedName: boolean;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   description?: string;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   details?: string;
+  doc?: string;
+  summary?: string;
   apiVersions: string[];
   onClient: boolean;
   clientDefaultValue?: any;
@@ -524,8 +548,16 @@ export interface SdkServiceResponseHeader {
   __raw: ModelProperty;
   serializedName: string;
   type: SdkType;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   description?: string;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   details?: string;
+  doc?: string;
+  summary?: string;
 }
 
 export interface SdkMethodResponse {
@@ -578,8 +610,16 @@ interface SdkMethodBase extends DecoratedType {
   access: AccessFlags;
   parameters: SdkParameter[];
   apiVersions: string[];
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   description?: string;
+  /**
+   * @deprecated Use `doc` and `summary` instead.
+   */
   details?: string;
+  doc?: string;
+  summary?: string;
   crossLanguageDefintionId: string;
 }
 

packages/typespec-client-generator-core/src/package.ts

@@ -2,8 +2,10 @@ import { getLroMetadata, getPagedResult } from "@azure-tools/typespec-azure-core
 import {
   createDiagnosticCollector,
   Diagnostic,
+  getDoc,
   getNamespaceFullName,
   getService,
+  getSummary,
   ignoreDiagnostics,
   Operation,
   Type,
@@ -255,6 +257,8 @@ function getSdkBasicServiceMethod<TServiceOperation extends SdkServiceOperation>
     parameters: methodParameters,
     description: getDocHelper(context, operation).description,
     details: getDocHelper(context, operation).details,
+    doc: getDoc(context.program, operation),
+    summary: getSummary(context.program, operation),
     operation: serviceOperation,
     response,
     apiVersions,
@@ -338,6 +342,7 @@ function getSdkInitializationType(
   return diagnostics.wrap({
     __raw: client.service,
     description: "Initialization class for the client",
+    doc: "Initialization class for the client",
     kind: "model",
     properties,
     name,
@@ -368,6 +373,8 @@ function getSdkMethodParameter(
       kind: "method",
       description: getDocHelper(context, type).description,
       details: getDocHelper(context, type).details,
+      doc: getDoc(context.program, type),
+      summary: getSummary(context.program, type),
       apiVersions,
       type: propertyType,
       name,
@@ -409,6 +416,8 @@ function getSdkMethods<TServiceOperation extends SdkServiceOperation>(
       name,
       description: getDocHelper(context, operationGroup.type).description,
       details: getDocHelper(context, operationGroup.type).details,
+      doc: getDoc(context.program, operationGroup.type),
+      summary: getSummary(context.program, operationGroup.type),
       access: "internal",
       response: operationGroupClient,
       apiVersions: getAvailableApiVersions(context, operationGroup.type, client.type),
@@ -434,6 +443,7 @@ function getEndpointTypeFromSingleServer(
         name: "endpoint",
         isGeneratedName: true,
         description: "Service host",
+        doc: "Service host",
         kind: "path",
         onClient: true,
         urlEncode: false,
@@ -538,6 +548,7 @@ function getSdkEndpointParameter(
     name: "endpoint",
     isGeneratedName: true,
     description: "Service host",
+    doc: "Service host",
     onClient: true,
     urlEncode: false,
     apiVersions: context.__tspTypeToApiVersions.get(client.type)!,
@@ -567,6 +578,8 @@ function createSdkClientType<TServiceOperation extends SdkServiceOperation>(
     name,
     description: docWrapper.description,
     details: docWrapper.details,
+    doc: getDoc(context.program, client.type),
+    summary: getSummary(context.program, client.type),
     methods: [],
     apiVersions: context.__tspTypeToApiVersions.get(client.type)!,
     nameSpace: getClientNamespaceStringHelper(context, client.service)!,

packages/typespec-client-generator-core/src/types.ts

@@ -21,9 +21,11 @@ import {
   Union,
   createDiagnosticCollector,
   getDiscriminator,
+  getDoc,
   getEncode,
   getFormat,
   getKnownValues,
+  getSummary,
   getVisibility,
   ignoreDiagnostics,
   isErrorModel,
@@ -265,6 +267,8 @@ function getSdkBuiltInTypeWithDiagnostics(
     encode: getEncodeHelper(context, type, kind),
     description: docWrapper.description,
     details: docWrapper.details,
+    doc: getDoc(context.program, type),
+    summary: getSummary(context.program, type),
     baseType:
       type.baseScalar && !context.program.checker.isStdType(type) // we only calculate the base type when this type has a base type and this type is not a std type because for std types there is no point of calculating its base type.
         ? diagnostics.pipe(getSdkBuiltInTypeWithDiagnostics(context, type.baseScalar, kind))
@@ -335,6 +339,8 @@ function getSdkDateTimeType(
     baseType: baseType,
     description: docWrapper.description,
     details: docWrapper.details,
+    doc: getDoc(context.program, type),
+    summary: getSummary(context.program, type),
     crossLanguageDefinitionId: getCrossLanguageDefinitionId(context, type),
   });
 }
@@ -434,6 +440,8 @@ function getSdkDurationTypeWithDiagnostics(
     baseType: baseType,
     description: docWrapper.description,
     details: docWrapper.details,
+    doc: getDoc(context.program, type),
+    summary: getSummary(context.program, type),
     crossLanguageDefinitionId: getCrossLanguageDefinitionId(context, type),
   });
 }
@@ -681,6 +689,7 @@ function addDiscriminatorToModelType(
     model.properties.splice(0, 0, {
       kind: "property",
       description: `Discriminator property for ${model.name}.`,
+      doc: `Discriminator property for ${model.name}.`,
       optional: false,
       discriminator: true,
       serializedName: discriminatorProperty
@@ -732,6 +741,8 @@ export function getSdkModelWithDiagnostics(
       isGeneratedName: !type.name,
       description: docWrapper.description,
       details: docWrapper.details,
+      doc: getDoc(context.program, type),
+      summary: getSummary(context.program, type),
       properties: [],
       additionalProperties: undefined, // going to set additional properties in the next few lines when we look at base model
       access: "public",
@@ -841,6 +852,8 @@ function getSdkEnumValueWithDiagnostics(
     value: type.value ?? type.name,
     description: docWrapper.description,
     details: docWrapper.details,
+    doc: getDoc(context.program, type),
+    summary: getSummary(context.program, type),
     enumType,
     valueType: enumType.valueType,
   });
@@ -865,6 +878,8 @@ function getSdkEnumWithDiagnostics(
       isGeneratedName: false,
       description: docWrapper.description,
       details: docWrapper.details,
+      doc: getDoc(context.program, type),
+      summary: getSummary(context.program, type),
       valueType: diagnostics.pipe(getSdkEnumValueType(context, type.members.values())),
       values: [],
       isFixed: true, // enums are always fixed after we switch to use union to represent extensible enum
@@ -900,6 +915,8 @@ function getSdkUnionEnumValues(
       name: name ? name : `${member.value}`,
       description: docWrapper.description,
       details: docWrapper.details,
+      doc: getDoc(context.program, member.type),
+      summary: getSummary(context.program, member.type),
       value: member.value,
       valueType: enumType.valueType,
       enumType,
@@ -929,6 +946,8 @@ export function getSdkUnionEnumWithDiagnostics(
       isGeneratedName: !type.union.name,
       description: docWrapper.description,
       details: docWrapper.details,
+      doc: getDoc(context.program, union),
+      summary: getSummary(context.program, union),
       valueType:
         diagnostics.pipe(getUnionAsEnumValueType(context, type.union)) ??
         diagnostics.pipe(getSdkEnumValueType(context, type.flattenedMembers.values())),
@@ -970,6 +989,8 @@ function getKnownValuesEnum(
         isGeneratedName: false,
         description: docWrapper.description,
         details: docWrapper.details,
+        doc: getDoc(context.program, type),
+        summary: getSummary(context.program, type),
         valueType: diagnostics.pipe(getSdkEnumValueType(context, knownValues.members.values())),
         values: [],
         isFixed: false,
@@ -1152,6 +1173,7 @@ export function getSdkCredentialParameter(
     name,
     isGeneratedName: true,
     description: "Credential used to authenticate requests to the service.",
+    doc: "Credential used to authenticate requests to the service.",
     apiVersions: getAvailableApiVersions(context, client.service, client.type),
     onClient: true,
     optional: false,
@@ -1182,6 +1204,8 @@ export function getSdkModelPropertyTypeBase(
     __raw: type,
     description: docWrapper.description,
     details: docWrapper.details,
+    doc: getDoc(context.program, type),
+    summary: getSummary(context.program, type),
     apiVersions,
     type: propertyType,
     name,

packages/typespec-client-generator-core/test/package.test.ts

@@ -1,4 +1,3 @@
-/* eslint-disable deprecation/deprecation */
 import { AzureCoreTestLibrary } from "@azure-tools/typespec-azure-core/testing";
 import { ApiKeyAuth, OAuth2Flow, Oauth2Auth } from "@typespec/http";
 import { deepStrictEqual, ok, strictEqual } from "assert";
@@ -142,7 +141,7 @@ describe("typespec-client-generator-core: package", () => {
       strictEqual(templateArg.kind, "path");
       strictEqual(templateArg.name, "endpoint");
       strictEqual(templateArg.serializedName, "endpoint");
-      strictEqual(templateArg.urlEncode, false);
+      strictEqual(templateArg.urlEncode, false); // eslint-disable-line deprecation/deprecation
       strictEqual(templateArg.type.kind, "string");
       strictEqual(templateArg.optional, false);
       strictEqual(templateArg.onClient, true);
@@ -334,11 +333,12 @@ describe("typespec-client-generator-core: package", () => {
       const templateArg = endpointParam.type.templateArguments[0];
       strictEqual(templateArg.kind, "path");
       strictEqual(templateArg.name, "endpointInput");
-      strictEqual(templateArg.urlEncode, false);
+      strictEqual(templateArg.urlEncode, false); // eslint-disable-line deprecation/deprecation
       strictEqual(templateArg.optional, false);
       strictEqual(templateArg.onClient, true);
       strictEqual(templateArg.clientDefaultValue, undefined);
-      strictEqual(templateArg.description, undefined);
+      strictEqual(templateArg.description, undefined); // eslint-disable-line deprecation/deprecation
+      strictEqual(templateArg.doc, undefined);
 
       const credentialParam = client.initialization.properties.filter(
         (p): p is SdkCredentialParameter => p.kind === "credential"
@@ -422,7 +422,7 @@ describe("typespec-client-generator-core: package", () => {
 
       const apiVersionParam = templatedEndpoint.templateArguments[1];
       strictEqual(apiVersionParam.clientDefaultValue, "v1.0");
-      strictEqual(apiVersionParam.urlEncode, true);
+      strictEqual(apiVersionParam.urlEncode, true); // eslint-disable-line deprecation/deprecation
       strictEqual(apiVersionParam.name, "apiVersion");
       strictEqual(apiVersionParam.onClient, true);
       strictEqual(apiVersionParam.optional, false);

packages/typespec-client-generator-core/test/public-utils.test.ts

@@ -1,4 +1,3 @@
-/* eslint-disable deprecation/deprecation */
 import { AzureCoreTestLibrary } from "@azure-tools/typespec-azure-core/testing";
 import {
   Model,

packages/typespec-client-generator-core/test/types/body-model-property-types.test.ts

@@ -1,4 +1,3 @@
-/* eslint-disable deprecation/deprecation */
 import { deepStrictEqual, ok, strictEqual } from "assert";
 import { beforeEach, describe, it } from "vitest";
 import { isReadOnly } from "../../src/types.js";

packages/typespec-client-generator-core/test/types/built-in-types.test.ts

@@ -1,4 +1,3 @@
-/* eslint-disable deprecation/deprecation */
 import { AzureCoreTestLibrary } from "@azure-tools/typespec-azure-core/testing";
 import { expectDiagnostics } from "@typespec/compiler/testing";
 import { ok, strictEqual } from "assert";
@@ -397,8 +396,10 @@ describe("typespec-client-generator-core: built-in types", () => {
     const type = models[0].properties[0].type;
     strictEqual(type.kind, "string");
     strictEqual(type.name, "TestScalar");
-    strictEqual(type.description, "title");
-    strictEqual(type.details, "doc");
+    strictEqual(type.description, "title"); // eslint-disable-line deprecation/deprecation
+    strictEqual(type.details, "doc"); // eslint-disable-line deprecation/deprecation
+    strictEqual(type.doc, "doc");
+    strictEqual(type.summary, "title");
     strictEqual(type.crossLanguageDefinitionId, "TestService.TestScalar");
   });
 

packages/typespec-client-generator-core/test/types/date-time-types.test.ts

@@ -164,8 +164,10 @@ describe("typespec-client-generator-core: date-time types", () => {
     strictEqual(sdkType.valueType.name, "unixTimestampDateTime");
     strictEqual(sdkType.valueType.encode, "unixTimestamp");
     strictEqual(sdkType.valueType.wireType?.kind, "int64");
-    strictEqual(sdkType.valueType.description, "title");
-    strictEqual(sdkType.valueType.details, "doc");
+    strictEqual(sdkType.valueType.description, "title"); // eslint-disable-line deprecation/deprecation
+    strictEqual(sdkType.valueType.details, "doc"); // eslint-disable-line deprecation/deprecation
+    strictEqual(sdkType.valueType.doc, "doc");
+    strictEqual(sdkType.valueType.summary, "title");
     strictEqual(sdkType.valueType.crossLanguageDefinitionId, "TestService.unixTimestampDateTime");
     strictEqual(sdkType.valueType.baseType?.kind, "utcDateTime");
     strictEqual(sdkType.valueType.baseType.wireType.kind, "string");