review feedback

packages/http-client-java/emitter/src/code-model-builder.ts

@@ -982,7 +982,7 @@ export class CodeModelBuilder {
     }
 
     // check for paged
-    this.processRouteForPaged(codeModelOperation, sdkMethod.operation.responses, sdkMethod);
+    this.processRouteForPaged(codeModelOperation, sdkMethod);
 
     // check for long-running operation
     this.processRouteForLongRunning(codeModelOperation, lroMetadata);
@@ -994,151 +994,151 @@ export class CodeModelBuilder {
 
   private processRouteForPaged(
     op: CodeModelOperation,
-    responses: SdkHttpResponse[],
     sdkMethod: SdkServiceMethod<SdkHttpOperation>,
   ) {
-    if (sdkMethod.kind === "paging" || sdkMethod.kind === "lropaging") {
-      for (const response of responses) {
-        const bodyType = response.type;
-        if (bodyType && bodyType.kind === "model") {
-          op.responses?.forEach((r) => {
-            if (r instanceof SchemaResponse) {
-              this.trackSchemaUsage(r.schema, { usage: [SchemaContext.Paged] });
-            }
-          });
+    const responses = sdkMethod.operation.responses;
+    if (sdkMethod.kind !== "paging" && sdkMethod.kind !== "lropaging") {
+      return;
+    }
 
-          function getLastPropertySegment(
-            segments: SdkModelPropertyType[] | undefined,
-          ): SdkBodyModelPropertyType | undefined {
-            if (segments) {
-              const lastSegment = segments[segments.length - 1];
-              if (lastSegment.kind === "property") {
-                return lastSegment;
-              }
-            }
-            return undefined;
+    for (const response of responses) {
+      const bodyType = response.type;
+      if (bodyType && bodyType.kind === "model") {
+        op.responses?.forEach((r) => {
+          if (r instanceof SchemaResponse) {
+            this.trackSchemaUsage(r.schema, { usage: [SchemaContext.Paged] });
           }
-          function getLastSegment(
-            segments: SdkModelPropertyType[] | undefined,
-          ): SdkModelPropertyType | undefined {
-            if (segments) {
-              return segments[segments.length - 1];
+        });
+
+        function getLastPropertySegment(
+          segments: SdkModelPropertyType[] | undefined,
+        ): SdkBodyModelPropertyType | undefined {
+          if (segments) {
+            const lastSegment = segments[segments.length - 1];
+            if (lastSegment.kind === "property") {
+              return lastSegment;
             }
-            return undefined;
           }
-          function getLastSegmentSerializedName(
-            segments: SdkModelPropertyType[] | undefined,
-          ): string | undefined {
-            const lastSegment = getLastPropertySegment(segments);
-            return lastSegment ? getPropertySerializedName(lastSegment) : undefined;
+          return undefined;
+        }
+        function getLastSegment(
+          segments: SdkModelPropertyType[] | undefined,
+        ): SdkModelPropertyType | undefined {
+          if (segments) {
+            return segments[segments.length - 1];
           }
+          return undefined;
+        }
+        function getLastSegmentSerializedName(
+          segments: SdkModelPropertyType[] | undefined,
+        ): string | undefined {
+          const lastSegment = getLastPropertySegment(segments);
+          return lastSegment ? getPropertySerializedName(lastSegment) : undefined;
+        }
 
-          // TODO: in future the property could be nested, so that the "itemSegments" or "nextLinkSegments" would contain more than 1 element
-          // item/result
-          // "itemsSegments" should exist for "paging"/"lropaging"
-          const itemSerializedName = getLastSegmentSerializedName(
-            sdkMethod.response.resultSegments,
+        // TODO: in future the property could be nested, so that the "itemSegments" or "nextLinkSegments" would contain more than 1 element
+        // item/result
+        // "itemsSegments" should exist for "paging"/"lropaging"
+        const itemSerializedName = getLastSegmentSerializedName(sdkMethod.response.resultSegments);
+        // nextLink
+        const nextLinkSerializedName = getLastSegmentSerializedName(
+          sdkMethod.pagingMetadata.nextLinkSegments,
+        );
+
+        // continuationToken
+        let continuationTokenParameter: Parameter | undefined;
+        let continuationTokenResponseProperty: Property[] | undefined;
+        let continuationTokenResponseHeader: HttpHeader | undefined;
+        if (!this.isBranded()) {
+          const continuationTokenParameterSegment = getLastSegment(
+            sdkMethod.pagingMetadata.continuationTokenParameterSegments,
           );
-          // nextLink
-          const nextLinkSerializedName = getLastSegmentSerializedName(
-            sdkMethod.pagingMetadata.nextLinkSegments,
+          const continuationTokenResponseSegment = getLastSegment(
+            sdkMethod.pagingMetadata.continuationTokenResponseSegments,
           );
-
-          // continuationToken
-          let continuationTokenParameter: Parameter | undefined;
-          let continuationTokenResponseProperty: Property[] | undefined;
-          let continuationTokenResponseHeader: HttpHeader | undefined;
-          if (!this.isBranded()) {
-            const continuationTokenParameterSegment = getLastSegment(
-              sdkMethod.pagingMetadata.continuationTokenParameterSegments,
+          if (continuationTokenParameterSegment && op.parameters) {
+            // for now, continuationToken is either request query or header parameter
+            const parameter = getHttpOperationParameter(
+              sdkMethod,
+              continuationTokenParameterSegment,
             );
-            const continuationTokenResponseSegment = getLastSegment(
-              sdkMethod.pagingMetadata.continuationTokenResponseSegments,
-            );
-            if (continuationTokenParameterSegment) {
-              // for now, continuationToken is either request query or header parameter
-              const parameter = getHttpOperationParameter(
-                sdkMethod,
-                continuationTokenParameterSegment,
-              );
-              if (parameter && op.parameters) {
-                for (const param of op.parameters) {
-                  if (param.protocol.http?.in === parameter.kind) {
+            if (parameter) {
+              for (const param of op.parameters) {
+                if (param.protocol.http?.in === parameter.kind) {
+                  if (
+                    parameter.kind === "header" &&
+                    param.language.default.serializedName.toLowerCase() ===
+                      parameter.serializedName.toLowerCase()
+                  ) {
+                    continuationTokenParameter = param;
+                    break;
+                  } else if (param.language.default.serializedName === parameter.serializedName) {
+                    continuationTokenParameter = param;
+                    break;
+                  }
+                }
+              }
+            }
+          }
+          if (continuationTokenResponseSegment && op.responses) {
+            if (continuationTokenResponseSegment?.kind === "responseheader") {
+              // continuationToken is response header
+              for (const response of op.responses) {
+                if (response instanceof SchemaResponse && response.protocol.http) {
+                  for (const header of response.protocol.http.headers) {
                     if (
-                      parameter.kind === "header" &&
-                      param.language.default.serializedName.toLowerCase() ===
-                        parameter.serializedName.toLowerCase()
+                      header.header.toLowerCase() ===
+                      continuationTokenResponseSegment.serializedName.toLowerCase()
                     ) {
-                      continuationTokenParameter = param;
-                      break;
-                    } else if (param.language.default.serializedName === parameter.serializedName) {
-                      continuationTokenParameter = param;
+                      continuationTokenResponseHeader = header;
                       break;
                     }
                   }
                 }
+                if (continuationTokenResponseHeader) {
+                  break;
+                }
               }
-            }
-            if (continuationTokenResponseSegment && op.responses) {
-              if (continuationTokenResponseSegment?.kind === "responseheader") {
-                // continuationToken is response header
-                for (const response of op.responses) {
-                  if (response instanceof SchemaResponse && response.protocol.http) {
-                    for (const header of response.protocol.http.headers) {
-                      if (
-                        header.header.toLowerCase() ===
-                        continuationTokenResponseSegment.serializedName.toLowerCase()
-                      ) {
-                        continuationTokenResponseHeader = header;
-                        break;
-                      }
+            } else if (continuationTokenResponseSegment?.kind === "property") {
+              // continuationToken is response body property
+              // TODO: the property could be nested
+              for (const response of op.responses) {
+                if (
+                  response instanceof SchemaResponse &&
+                  response.schema instanceof ObjectSchema &&
+                  response.schema.properties
+                ) {
+                  for (const property of response.schema.properties) {
+                    if (
+                      property.serializedName ===
+                      getPropertySerializedName(continuationTokenResponseSegment)
+                    ) {
+                      continuationTokenResponseProperty = [property];
+                      break;
                     }
                   }
-                  if (continuationTokenResponseHeader) {
-                    break;
-                  }
                 }
-              } else if (continuationTokenResponseSegment?.kind === "property") {
-                // continuationToken is response body property
-                // TODO: the property could be nested
-                for (const response of op.responses) {
-                  if (
-                    response instanceof SchemaResponse &&
-                    response.schema instanceof ObjectSchema &&
-                    response.schema.properties
-                  ) {
-                    for (const property of response.schema.properties) {
-                      if (
-                        property.serializedName ===
-                        getPropertySerializedName(continuationTokenResponseSegment)
-                      ) {
-                        continuationTokenResponseProperty = [property];
-                        break;
-                      }
-                    }
-                  }
-                  if (continuationTokenResponseProperty) {
-                    break;
-                  }
+                if (continuationTokenResponseProperty) {
+                  break;
                 }
               }
             }
           }
-
-          op.extensions = op.extensions ?? {};
-          op.extensions["x-ms-pageable"] = {
-            itemName: itemSerializedName,
-            nextLinkName: nextLinkSerializedName,
-            continuationToken: continuationTokenParameter
-              ? new PageableContinuationToken(
-                  continuationTokenParameter,
-                  continuationTokenResponseProperty,
-                  continuationTokenResponseHeader,
-                )
-              : undefined,
-          };
-          break;
         }
+
+        op.extensions = op.extensions ?? {};
+        op.extensions["x-ms-pageable"] = {
+          itemName: itemSerializedName,
+          nextLinkName: nextLinkSerializedName,
+          continuationToken: continuationTokenParameter
+            ? new PageableContinuationToken(
+                continuationTokenParameter,
+                continuationTokenResponseProperty,
+                continuationTokenResponseHeader,
+              )
+            : undefined,
+        };
+        break;
       }
     }
   }

packages/http-client-java/emitter/src/common/client.ts

@@ -20,9 +20,21 @@ export interface Client extends Aspect {
 
   serviceVersion?: ServiceVersion; // apiVersions is in
 
+  /**
+   * Parent client of this client, if exists.
+   */
   parent?: Client;
+  /**
+   * Sub clients of this client, if exists.
+   */
   subClients: Array<Client>;
+  /**
+   * Whether the Builder class has a public method (e.g. "buildSubClient") to initiate this client.
+   */
   buildMethodPublic: boolean;
+  /**
+   * Whether the parent client has a public accessor method (e.g. "getSubClient") to initiate this client.
+   */
   parentAccessorPublic: boolean;
 }
 
@@ -76,13 +88,27 @@ export class ServiceVersion extends Metadata {
 }
 
 export interface EncodedSchema {
+  /**
+   * The encoded type -- the type on wire.
+   * E.g., the type for SDK maybe "int32", but type on wire be "string".
+   */
   encode?: string;
 }
 
 export class PageableContinuationToken {
+  /**
+   * The parameter of the operation as continuationToken in API request.
+   */
   parameter: Parameter;
   // responseProperty and responseHeader is mutally exclusive
-  responseProperty?: Property[];
+  /**
+   * The reference to response body property of the operation as continuationToken in API request.
+   * Array because the property may be at "links.nextToken".
+   */
+  responseProperty?: Array<Property>;
+  /**
+   * The reference to response header of the operation as continuationToken in API request.
+   */
   responseHeader?: HttpHeader;
 
   constructor(parameter: Parameter, responseProperty?: Property[], responseHeader?: HttpHeader) {