Skip to content

Commit

Permalink
http-client-java, emitter, deprecate description and details (#4529)
Browse files Browse the repository at this point in the history 
Fix #4394

Code changes: 
1. deprecate `description` and `details`, use `doc` and `summary`
instead.
2. add `npm run lint` in `Build-Packages.ps1`. So that deprecation
warning will be thrown.


I quickly checked the generation diff. The generation diffs are in cases
where the operation uses tsp template, previously, the `description`
will get tempalte's doc, but now `doc` or `summary` will not. **It only
impacts impl classes**. I think it is acceptable.
eg.,
[code](https://github.com/microsoft/typespec/pull/4529/files#diff-71f0d715f644a82637d8db144d6d3a999b65d05a7b44bd1570306e46c2c83beeL532),
below highlighted template's doc will disappear now.
```diff
  @get
  listWithEtag is StandardResourceOperations.ResourceList<
    Resource,
    ResponseHeadersTrait<EtagResponseEnvelope>
  >;

  /**
++   * Resource list operation template.
   * @template Resource Resource type.
   * @template Traits Object describing the traits of the operation.
   */
  @Foundations.Private.ensureVerb("ResourceList", "GET")
  ResourceList<
    Resource extends TypeSpec.Reflection.Model,
    Traits extends TypeSpec.Reflection.Model = {}
  > is Foundations.ResourceList<
    Resource,
    TraitProperties<Traits & InterfaceTraits, TraitLocation.Parameters, TraitContext.List>,
    Foundations.CustomPage<Resource, Traits & InterfaceTraits>,
    Traits & InterfaceTraits,
    ErrorResponse
  >;
```
  • Loading branch information
@haolingdong-msft
haolingdong-msft authored Sep 26, 2024
1 parent fa68969 commit 378c4e0
Show file tree
Hide file tree
Showing 15 changed files with 63 additions and 136 deletions.
120 changes: 60 additions & 60 deletions packages/http-client-java/emitter/src/code-model-builder.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -280,7 +280,7 @@ export class CodeModelBuilder {
this.trackSchemaUsage(schema, {
usage: [SchemaContext.Input, SchemaContext.Output /*SchemaContext.Public*/],
});
parameter = new Parameter(arg.name, arg.description ?? "", schema, {
parameter = new Parameter(arg.name, arg.doc ?? "", schema, {
implementation: ImplementationLocation.Client,
origin: "modelerfour:synthesized/host",
required: true,
Expand Down Expand Up @@ -496,8 +496,8 @@ export class CodeModelBuilder {
javaNamespace = this.getJavaNamespace(this.namespace + "." + clientSubNamespace);
}

const codeModelClient = new CodeModelClient(clientName, client.details ?? "", {
summary: client.description,
const codeModelClient = new CodeModelClient(clientName, client.doc ?? "", {
summary: client.summary,
language: {
default: {
namespace: this.namespace,
Expand Down Expand Up @@ -759,9 +759,9 @@ export class CodeModelBuilder {

const operationExamples = this.getOperationExample(sdkMethod);

const codeModelOperation = new CodeModelOperation(operationName, sdkMethod.details ?? "", {
const codeModelOperation = new CodeModelOperation(operationName, sdkMethod.doc ?? "", {
operationId: operationId,
summary: sdkMethod.description,
summary: sdkMethod.summary,
extensions: {
"x-ms-examples": operationExamples,
},
Expand Down Expand Up @@ -1166,8 +1166,8 @@ export class CodeModelBuilder {
param.correspondingMethodParams[0].onClient;

const nullable = param.type.kind === "nullable";
const parameter = new Parameter(param.name, param.details ?? "", schema, {
summary: param.description,
const parameter = new Parameter(param.name, param.doc ?? "", schema, {
summary: param.summary,
implementation: parameterOnClient
? ImplementationLocation.Client
: ImplementationLocation.Method,
Expand Down Expand Up @@ -1365,8 +1365,8 @@ export class CodeModelBuilder {
}

const parameterName = sdkBody.name;
const parameter = new Parameter(parameterName, sdkBody.description ?? "", schema, {
summary: sdkBody.details,
const parameter = new Parameter(parameterName, sdkBody.doc ?? "", schema, {
summary: sdkBody.summary,
implementation: ImplementationLocation.Method,
required: !sdkBody.optional,
protocol: {
Expand Down Expand Up @@ -1625,7 +1625,7 @@ export class CodeModelBuilder {
language: {
default: {
name: header.serializedName,
description: header.description ?? header.details,
description: header.summary ?? header.doc,
},
},
}),
Expand Down Expand Up @@ -1831,17 +1831,17 @@ export class CodeModelBuilder {

private processStringSchema(type: SdkBuiltInType, name: string): StringSchema {
return this.codeModel.schemas.add(
new StringSchema(name, type.details ?? "", {
summary: type.description,
new StringSchema(name, type.doc ?? "", {
summary: type.summary,
}),
);
}

private processByteArraySchema(type: SdkBuiltInType, name: string): ByteArraySchema {
const base64Encoded: boolean = type.encode === "base64url";
return this.codeModel.schemas.add(
new ByteArraySchema(name, type.details ?? "", {
summary: type.description,
new ByteArraySchema(name, type.doc ?? "", {
summary: type.summary,
format: base64Encoded ? "base64url" : "byte",
}),
);
Expand All @@ -1852,8 +1852,8 @@ export class CodeModelBuilder {
name: string,
precision: number,
): NumberSchema {
const schema = new NumberSchema(name, type.details ?? "", SchemaType.Integer, precision, {
summary: type.description,
const schema = new NumberSchema(name, type.doc ?? "", SchemaType.Integer, precision, {
summary: type.summary,
});
if (type.encode === "string") {
(schema as EncodedSchema).encode = type.encode;
Expand All @@ -1863,25 +1863,25 @@ export class CodeModelBuilder {

private processNumberSchema(type: SdkBuiltInType, name: string): NumberSchema {
return this.codeModel.schemas.add(
new NumberSchema(name, type.details ?? "", SchemaType.Number, 64, {
summary: type.description,
new NumberSchema(name, type.doc ?? "", SchemaType.Number, 64, {
summary: type.summary,
}),
);
}

private processDecimalSchema(type: SdkBuiltInType, name: string): NumberSchema {
// "Infinity" maps to "BigDecimal" in Java
return this.codeModel.schemas.add(
new NumberSchema(name, type.details ?? "", SchemaType.Number, Infinity, {
summary: type.description,
new NumberSchema(name, type.doc ?? "", SchemaType.Number, Infinity, {
summary: type.summary,
}),
);
}

private processBooleanSchema(type: SdkBuiltInType, name: string): BooleanSchema {
return this.codeModel.schemas.add(
new BooleanSchema(name, type.details ?? "", {
summary: type.description,
new BooleanSchema(name, type.doc ?? "", {
summary: type.summary,
}),
);
}
Expand All @@ -1896,16 +1896,16 @@ export class CodeModelBuilder {

const elementSchema = this.processSchema(elementType, name);
return this.codeModel.schemas.add(
new ArraySchema(name, type.details ?? "", elementSchema, {
summary: type.description,
new ArraySchema(name, type.doc ?? "", elementSchema, {
summary: type.summary,
nullableItems: nullableItems,
}),
);
}

private processDictionarySchema(type: SdkDictionaryType, name: string): DictionarySchema {
const dictSchema = new DictionarySchema<any>(name, type.details ?? "", null, {
summary: type.description,
const dictSchema = new DictionarySchema<any>(name, type.doc ?? "", null, {
summary: type.summary,
});

// cache this now before we accidentally recurse on this type.
Expand Down Expand Up @@ -1937,13 +1937,13 @@ export class CodeModelBuilder {

const choices: ChoiceValue[] = [];
type.values.forEach((it: SdkEnumValueType) =>
choices.push(new ChoiceValue(it.name, it.description ?? "", it.value ?? it.name)),
choices.push(new ChoiceValue(it.name, it.doc ?? "", it.value ?? it.name)),
);

const schemaType = type.isFixed ? SealedChoiceSchema : ChoiceSchema;

const schema = new schemaType(type.name ?? name, type.details ?? "", {
summary: type.description,
const schema = new schemaType(type.name ?? name, type.doc ?? "", {
summary: type.summary,
choiceType: valueType as any,
choices: choices,
language: {
Expand All @@ -1963,8 +1963,8 @@ export class CodeModelBuilder {
const valueType = this.processSchema(type.valueType, type.valueType.kind);

return this.codeModel.schemas.add(
new ConstantSchema(type.name ?? name, type.details ?? "", {
summary: type.description,
new ConstantSchema(type.name ?? name, type.doc ?? "", {
summary: type.summary,
valueType: valueType,
value: new ConstantValue(type.value),
}),
Expand All @@ -1975,8 +1975,8 @@ export class CodeModelBuilder {
const valueType = this.processSchema(type.enumType, type.enumType.name);

return this.codeModel.schemas.add(
new ConstantSchema(type.name ?? name, type.details ?? "", {
summary: type.description,
new ConstantSchema(type.name ?? name, type.doc ?? "", {
summary: type.summary,
valueType: valueType,
value: new ConstantValue(type.value ?? type.name),
}),
Expand All @@ -1985,8 +1985,8 @@ export class CodeModelBuilder {

private processUnixTimeSchema(type: SdkDateTimeType, name: string): UnixTimeSchema {
return this.codeModel.schemas.add(
new UnixTimeSchema(name, type.details ?? "", {
summary: type.description,
new UnixTimeSchema(name, type.doc ?? "", {
summary: type.summary,
}),
);
}
Expand All @@ -1997,25 +1997,25 @@ export class CodeModelBuilder {
rfc1123: boolean,
): DateTimeSchema {
return this.codeModel.schemas.add(
new DateTimeSchema(name, type.details ?? "", {
summary: type.description,
new DateTimeSchema(name, type.doc ?? "", {
summary: type.summary,
format: rfc1123 ? "date-time-rfc1123" : "date-time",
}),
);
}

private processDateSchema(type: SdkBuiltInType, name: string): DateSchema {
return this.codeModel.schemas.add(
new DateSchema(name, type.details ?? "", {
summary: type.description,
new DateSchema(name, type.doc ?? "", {
summary: type.summary,
}),
);
}

private processTimeSchema(type: SdkBuiltInType, name: string): TimeSchema {
return this.codeModel.schemas.add(
new TimeSchema(name, type.details ?? "", {
summary: type.description,
new TimeSchema(name, type.doc ?? "", {
summary: type.summary,
}),
);
}
Expand All @@ -2026,26 +2026,26 @@ export class CodeModelBuilder {
format: DurationSchema["format"] = "duration-rfc3339",
): DurationSchema {
return this.codeModel.schemas.add(
new DurationSchema(name, type.details ?? "", {
summary: type.description,
new DurationSchema(name, type.doc ?? "", {
summary: type.summary,
format: format,
}),
);
}

private processUrlSchema(type: SdkBuiltInType, name: string): UriSchema {
return this.codeModel.schemas.add(
new UriSchema(name, type.details ?? "", {
summary: type.description,
new UriSchema(name, type.doc ?? "", {
summary: type.summary,
}),
);
}

private processObjectSchema(type: SdkModelType, name: string): ObjectSchema {
const rawModelType = type.__raw;
const namespace = getNamespace(rawModelType);
const objectSchema = new ObjectSchema(name, type.details ?? "", {
summary: type.description,
const objectSchema = new ObjectSchema(name, type.doc ?? "", {
summary: type.summary,
language: {
default: {
namespace: namespace,
Expand Down Expand Up @@ -2111,7 +2111,7 @@ export class CodeModelBuilder {
name: "string",
crossLanguageDefinitionId: type.crossLanguageDefinitionId,
},
description: type.description,
description: type.doc,
valueType: type.additionalProperties,
decorators: [],
};
Expand Down Expand Up @@ -2196,8 +2196,8 @@ export class CodeModelBuilder {
schema = this.processSchema(nonNullType, "");
}

return new Property(prop.name, prop.details ?? "", schema, {
summary: prop.description,
return new Property(prop.name, prop.doc ?? "", schema, {
summary: prop.summary,
required: !prop.optional,
nullable: nullable,
readOnly: this.isReadOnly(prop),
Expand All @@ -2216,8 +2216,8 @@ export class CodeModelBuilder {
this.logWarning(
`Convert TypeSpec Union '${getUnionDescription(rawUnionType, this.typeNameOptions)}' to Class '${baseName}'`,
);
const unionSchema = new OrSchema(baseName + "Base", type.details ?? "", {
summary: type.description,
const unionSchema = new OrSchema(baseName + "Base", type.doc ?? "", {
summary: type.summary,
});
unionSchema.anyOf = [];
type.variantTypes.forEach((it) => {
Expand All @@ -2226,8 +2226,8 @@ export class CodeModelBuilder {
const propertyName = "value";

// these ObjectSchema is not added to codeModel.schemas
const objectSchema = new ObjectSchema(modelName, it.details ?? "", {
summary: it.description,
const objectSchema = new ObjectSchema(modelName, it.doc ?? "", {
summary: it.summary,
language: {
default: {
namespace: namespace,
Expand All @@ -2240,8 +2240,8 @@ export class CodeModelBuilder {

const variantSchema = this.processSchema(it, variantName);
objectSchema.addProperty(
new Property(propertyName, type.details ?? "", variantSchema, {
summary: type.description,
new Property(propertyName, type.doc ?? "", variantSchema, {
summary: type.summary,
required: true,
readOnly: false,
}),
Expand All @@ -2253,8 +2253,8 @@ export class CodeModelBuilder {

private processBinarySchema(type: SdkBuiltInType): BinarySchema {
return this.codeModel.schemas.add(
new BinarySchema(type.description ?? "", {
summary: type.details,
new BinarySchema(type.doc ?? "", {
summary: type.summary,
}),
);
}
Expand Down Expand Up @@ -2352,7 +2352,7 @@ export class CodeModelBuilder {
processSchemaFunc,
),
{
summary: property.description,
summary: property.summary,
},
);
} else {
Expand Down Expand Up @@ -2589,7 +2589,7 @@ export class CodeModelBuilder {

private subscriptionIdParameter(parameter: SdkPathParameter): Parameter {
if (!this._subscriptionParameter) {
const description = parameter.description;
const description = parameter.doc;
this._subscriptionParameter = new Parameter(
"subscriptionId",
description ? description : "The ID of the target subscription.",
Expand Down
3 changes: 3 additions & 0 deletions packages/http-client-java/eng/scripts/Build-Packages.ps1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,9 @@ try {

Invoke-LoggedCommand "npm run build" -GroupOutput

# linting
Invoke-LoggedCommand "npm run build" -GroupOutput

#pack the emitter
$file = Invoke-LoggedCommand "npm pack -q"
Copy-Item $file -Destination "$outputPath/packages"
Expand Down
Loading

0 comments on commit 378c4e0

Please sign in to comment.