feat: add comments for page stream method (#116)

* add comments for page strea,m * add line between page & page stream method
googleapis · Nov 8, 2019 · c6a185a · c6a185a
1 parent ba9891b
commit c6a185a
Show file tree

Hide file tree

Showing 5 changed files with 278 additions and 37 deletions.
diff --git a/templates/typescript_gapic/_util.njk b/templates/typescript_gapic/_util.njk
@@ -15,22 +15,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 -#}
-{%- macro initRequestWithHeaderParam(method) -%}
-            const request: protosTypes{{ toInterface(method.inputInterface) }} = {};
-{%- if method.headerRequestParams.length > 1 %}
-{%- set chain = "request" -%}
-{%- for field in method.headerRequestParams.slice(0, -1) %}
-            {{ chain }}.{{ field.toCamelCase() }} = {};
-{%- set chain = chain + "." + field.toCamelCase() -%}
-{%- endfor %}
-            {{ chain }}.{{ method.headerRequestParams.slice(-1)[0] }} = '';
-{%- endif %}
-{%- endmacro -%}
-
-{%- macro toInterface(type) -%}
-{%- set index = type.lastIndexOf('.') -%}
-{{ type.substring(0, index + 1) + 'I' + type.substring(index + 1) }}
-{%- endmacro -%}
 
 {%- macro printComments(method, service) -%}
   {{- printCommentsForMethod(method) }}
@@ -40,22 +24,19 @@ limitations under the License.
   {{- printReturn(method, service) }}
 {%- endmacro %}
 
-{%- macro printCommentsForParams(method) -%}
-{% if not method.clientStreaming %}
-{%- set commentsMap = method.paramComment -%}
-{%- for oneComment in commentsMap -%}
-{%- set type = oneComment.paramType -%}
-{%- if type.startsWith('.') %}
- * @param { {{- type.substring(1) -}} } request.{{ oneComment.paramName }}
-{%- else %}
- * @param { {{- convertParamType(oneComment.paramType) -}} } request.{{ oneComment.paramName }}
-{%- endif -%}
-{%- set lines = oneComment.comments -%}
-{%- for line in lines %} 
- *  {{ line.replaceAll('*/', '* /') | safe}} 
-{%- endfor -%}
-{%- endfor -%}
-{%- endif %}
+{%- macro printCommentsPageStream(method) -%}
+  {{- printPageStreamHeader(method) -}}
+  {{- printRequest(method) -}}
+  {{- printCommentsForParams(method) -}}
+  {{- printOptions() -}}
+  {{- printReturnPageStream(method) }}
+{%- endmacro -%}
+
+{%- macro printCommentsForService(service) -%}
+{%- set lines = service.comments -%}
+{% for line in lines %}
+ * {{ line | safe}}
+{%- endfor %}
 {%- endmacro -%}
 
 {%- macro printCommentsForMethod(method) -%}
@@ -65,11 +46,19 @@ limitations under the License.
 {%- endfor %}
 {%- endmacro -%}
 
-{%- macro printCommentsForService(service) -%}
-{%- set lines = service.comments -%}
-{% for line in lines %}
- * {{ line | safe}}
-{%- endfor %}
+{%- macro printPageStreamHeader(method) %}
+ * Equivalent to {@link {{ method.name.toCamelCase() }}}, but returns a NodeJS Stream object.
+ *
+ * This fetches the paged responses for {@link {{ method.name.toCamelCase() }}} continuously
+ * and invokes the callback registered for 'data' event for each element in the
+ * responses.
+ *
+ * The returned object has 'end' method when no more elements are required.
+ *
+ * autoPaginate option will be ignored.
+ *
+ * @see {@link https://nodejs.org/api/stream.html}
+ *
 {%- endmacro -%}
 
 {%- macro printRequest(method) %}
@@ -79,6 +68,24 @@ limitations under the License.
 {%- endif %}
 {%- endmacro -%}
 
+{%- macro printCommentsForParams(method) -%}
+{% if not method.clientStreaming %}
+{%- set commentsMap = method.paramComment -%}
+{%- for oneComment in commentsMap -%}
+{%- set type = oneComment.paramType -%}
+{%- if type.startsWith('.') %}
+ * @param { {{- type.substring(1) -}} } request.{{ oneComment.paramName }}
+{%- else %}
+ * @param { {{- convertParamType(oneComment.paramType) -}} } request.{{ oneComment.paramName }}
+{%- endif -%}
+{%- set lines = oneComment.comments -%}
+{%- for line in lines %} 
+ *  {{ line.replaceAll('*/', '* /') | safe}} 
+{%- endfor -%}
+{%- endfor -%}
+{%- endif %}
+{%- endmacro -%}
+
 {%- macro printOptions(type) %}
  * @param {object} [options]
  *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
@@ -132,11 +139,33 @@ limitations under the License.
  *   will emit objects representing [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}} on 'data' event asynchronously.
 {%- endmacro -%}
 
+{%- macro printReturnPageStream(method) %}
+ * @returns {Stream}
+ *   An object stream which emits an object representing [{{- toMessageName(method.pagingResponseType) -}}]{@link {{ method.pagingResponseType.substring(1) }}} on 'data' event.
+{%- endmacro -%}
+
 {%- macro toMessageName(messageType) -%}
 {%- set arr = messageType.split('.') %}
 {{- arr[arr.length - 1] -}}
 {%- endmacro -%}
 
+{%- macro initRequestWithHeaderParam(method) -%}
+            const request: protosTypes{{ toInterface(method.inputInterface) }} = {};
+{%- if method.headerRequestParams.length > 1 %}
+{%- set chain = "request" -%}
+{%- for field in method.headerRequestParams.slice(0, -1) %}
+            {{ chain }}.{{ field.toCamelCase() }} = {};
+{%- set chain = chain + "." + field.toCamelCase() -%}
+{%- endfor %}
+            {{ chain }}.{{ method.headerRequestParams.slice(-1)[0] }} = '';
+{%- endif %}
+{%- endmacro -%}
+
+{%- macro toInterface(type) -%}
+{%- set index = type.lastIndexOf('.') -%}
+{{ type.substring(0, index + 1) + 'I' + type.substring(index + 1) }}
+{%- endmacro -%}
+
 {%- macro convertParamType(paramType) -%}
 {%- if paramType.includes('TYPE_BYTES') %}
 {%- set type = paramType.replace('TYPE_BYTES', 'Buffer') %}

diff --git a/templates/typescript_gapic/src/$version/$service_client.ts.njk b/templates/typescript_gapic/src/$version/$service_client.ts.njk
@@ -569,6 +569,9 @@ export class {{ service.name }}Client {
     return this._innerApiCalls.{{ method.name.toCamelCase() }}(request, options, callback);
   } 
 
+/**
+{{- util.printCommentsPageStream(method) }}
+ */
   {{ method.name.toCamelCase() }}Stream(
       request?: protosTypes{{ util.toInterface(method.inputInterface) }},
       options?: gax.CallOptions | {}):

diff --git a/typescript/test/testdata/keymanager/src/v1/key_management_service_client.ts.baseline b/typescript/test/testdata/keymanager/src/v1/key_management_service_client.ts.baseline
@@ -1634,6 +1634,42 @@ export class KeyManagementServiceClient {
     return this._innerApiCalls.listKeyRings(request, options, callback);
   } 
 
+/**
+ * Equivalent to {@link listKeyRings}, but returns a NodeJS Stream object.
+ *
+ * This fetches the paged responses for {@link listKeyRings} continuously
+ * and invokes the callback registered for 'data' event for each element in the
+ * responses.
+ *
+ * The returned object has 'end' method when no more elements are required.
+ *
+ * autoPaginate option will be ignored.
+ *
+ * @see {@link https://nodejs.org/api/stream.html}
+ *
+ * @param {Object} request
+ *   The request object that will be sent.
+ * @param {string} request.parent 
+ *   Required. The resource name of the location associated with the 
+ *   [KeyRings][google.cloud.kms.v1.KeyRing], in the format `projects/* /locations/*`.
+ * @param {number} request.page_size 
+ *   Optional limit on the number of [KeyRings][google.cloud.kms.v1.KeyRing] to include in the 
+ *   response.  Further [KeyRings][google.cloud.kms.v1.KeyRing] can subsequently be obtained by 
+ *   including the [ListKeyRingsResponse.next_page_token][google.cloud.kms.v1.ListKeyRingsResponse.next_page_token] in a subsequent 
+ *   request.  If unspecified, the server will pick an appropriate default.
+ * @param {string} request.page_token 
+ *   Optional pagination token, returned earlier via 
+ *   [ListKeyRingsResponse.next_page_token][google.cloud.kms.v1.ListKeyRingsResponse.next_page_token].
+ * @param {string} request.filter 
+ *   Optional. Only include resources that match the filter in the response.
+ * @param {string} request.order_by 
+ *   Optional. Specify how the results should be sorted. If not specified, the 
+ *   results will be sorted in the default order.
+ * @param {object} [options]
+ *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+ * @returns {Stream}
+ *   An object stream which emits an object representing [KeyRing]{@link google.cloud.kms.v1.KeyRing} on 'data' event.
+ */
   listKeyRingsStream(
       request?: protosTypes.google.cloud.kms.v1.IListKeyRingsRequest,
       options?: gax.CallOptions | {}):
@@ -1732,6 +1768,44 @@ export class KeyManagementServiceClient {
     return this._innerApiCalls.listCryptoKeys(request, options, callback);
   } 
 
+/**
+ * Equivalent to {@link listCryptoKeys}, but returns a NodeJS Stream object.
+ *
+ * This fetches the paged responses for {@link listCryptoKeys} continuously
+ * and invokes the callback registered for 'data' event for each element in the
+ * responses.
+ *
+ * The returned object has 'end' method when no more elements are required.
+ *
+ * autoPaginate option will be ignored.
+ *
+ * @see {@link https://nodejs.org/api/stream.html}
+ *
+ * @param {Object} request
+ *   The request object that will be sent.
+ * @param {string} request.parent 
+ *   Required. The resource name of the [KeyRing][google.cloud.kms.v1.KeyRing] to list, in the format 
+ *   `projects/* /locations/* /keyRings/*`.
+ * @param {number} request.page_size 
+ *   Optional limit on the number of [CryptoKeys][google.cloud.kms.v1.CryptoKey] to include in the 
+ *   response.  Further [CryptoKeys][google.cloud.kms.v1.CryptoKey] can subsequently be obtained by 
+ *   including the [ListCryptoKeysResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeysResponse.next_page_token] in a subsequent 
+ *   request.  If unspecified, the server will pick an appropriate default.
+ * @param {string} request.page_token 
+ *   Optional pagination token, returned earlier via 
+ *   [ListCryptoKeysResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeysResponse.next_page_token].
+ * @param {google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionView} request.version_view 
+ *   The fields of the primary version to include in the response.
+ * @param {string} request.filter 
+ *   Optional. Only include resources that match the filter in the response.
+ * @param {string} request.order_by 
+ *   Optional. Specify how the results should be sorted. If not specified, the 
+ *   results will be sorted in the default order.
+ * @param {object} [options]
+ *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+ * @returns {Stream}
+ *   An object stream which emits an object representing [CryptoKey]{@link google.cloud.kms.v1.CryptoKey} on 'data' event.
+ */
   listCryptoKeysStream(
       request?: protosTypes.google.cloud.kms.v1.IListCryptoKeysRequest,
       options?: gax.CallOptions | {}):
@@ -1831,6 +1905,45 @@ export class KeyManagementServiceClient {
     return this._innerApiCalls.listCryptoKeyVersions(request, options, callback);
   } 
 
+/**
+ * Equivalent to {@link listCryptoKeyVersions}, but returns a NodeJS Stream object.
+ *
+ * This fetches the paged responses for {@link listCryptoKeyVersions} continuously
+ * and invokes the callback registered for 'data' event for each element in the
+ * responses.
+ *
+ * The returned object has 'end' method when no more elements are required.
+ *
+ * autoPaginate option will be ignored.
+ *
+ * @see {@link https://nodejs.org/api/stream.html}
+ *
+ * @param {Object} request
+ *   The request object that will be sent.
+ * @param {string} request.parent 
+ *   Required. The resource name of the [CryptoKey][google.cloud.kms.v1.CryptoKey] to list, in the format 
+ *   `projects/* /locations/* /keyRings/* /cryptoKeys/*`.
+ * @param {number} request.page_size 
+ *   Optional limit on the number of [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] to 
+ *   include in the response. Further [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] can 
+ *   subsequently be obtained by including the 
+ *   [ListCryptoKeyVersionsResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeyVersionsResponse.next_page_token] in a subsequent request. 
+ *   If unspecified, the server will pick an appropriate default.
+ * @param {string} request.page_token 
+ *   Optional pagination token, returned earlier via 
+ *   [ListCryptoKeyVersionsResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeyVersionsResponse.next_page_token].
+ * @param {google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionView} request.view 
+ *   The fields to include in the response.
+ * @param {string} request.filter 
+ *   Optional. Only include resources that match the filter in the response.
+ * @param {string} request.order_by 
+ *   Optional. Specify how the results should be sorted. If not specified, the 
+ *   results will be sorted in the default order.
+ * @param {object} [options]
+ *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+ * @returns {Stream}
+ *   An object stream which emits an object representing [CryptoKeyVersion]{@link google.cloud.kms.v1.CryptoKeyVersion} on 'data' event.
+ */
   listCryptoKeyVersionsStream(
       request?: protosTypes.google.cloud.kms.v1.IListCryptoKeyVersionsRequest,
       options?: gax.CallOptions | {}):
@@ -1927,6 +2040,42 @@ export class KeyManagementServiceClient {
     return this._innerApiCalls.listImportJobs(request, options, callback);
   } 
 
+/**
+ * Equivalent to {@link listImportJobs}, but returns a NodeJS Stream object.
+ *
+ * This fetches the paged responses for {@link listImportJobs} continuously
+ * and invokes the callback registered for 'data' event for each element in the
+ * responses.
+ *
+ * The returned object has 'end' method when no more elements are required.
+ *
+ * autoPaginate option will be ignored.
+ *
+ * @see {@link https://nodejs.org/api/stream.html}
+ *
+ * @param {Object} request
+ *   The request object that will be sent.
+ * @param {string} request.parent 
+ *   Required. The resource name of the [KeyRing][google.cloud.kms.v1.KeyRing] to list, in the format 
+ *   `projects/* /locations/* /keyRings/*`.
+ * @param {number} request.page_size 
+ *   Optional limit on the number of [ImportJobs][google.cloud.kms.v1.ImportJob] to include in the 
+ *   response. Further [ImportJobs][google.cloud.kms.v1.ImportJob] can subsequently be obtained by 
+ *   including the [ListImportJobsResponse.next_page_token][google.cloud.kms.v1.ListImportJobsResponse.next_page_token] in a subsequent 
+ *   request. If unspecified, the server will pick an appropriate default.
+ * @param {string} request.page_token 
+ *   Optional pagination token, returned earlier via 
+ *   [ListImportJobsResponse.next_page_token][google.cloud.kms.v1.ListImportJobsResponse.next_page_token].
+ * @param {string} request.filter 
+ *   Optional. Only include resources that match the filter in the response.
+ * @param {string} request.order_by 
+ *   Optional. Specify how the results should be sorted. If not specified, the 
+ *   results will be sorted in the default order.
+ * @param {object} [options]
+ *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+ * @returns {Stream}
+ *   An object stream which emits an object representing [ImportJob]{@link google.cloud.kms.v1.ImportJob} on 'data' event.
+ */
   listImportJobsStream(
       request?: protosTypes.google.cloud.kms.v1.IListImportJobsRequest,
       options?: gax.CallOptions | {}):

diff --git a/typescript/test/testdata/showcase/src/v1beta1/echo_client.ts.baseline b/typescript/test/testdata/showcase/src/v1beta1/echo_client.ts.baseline
@@ -565,6 +565,32 @@ export class EchoClient {
     return this._innerApiCalls.pagedExpand(request, options, callback);
   } 
 
+/**
+ * Equivalent to {@link pagedExpand}, but returns a NodeJS Stream object.
+ *
+ * This fetches the paged responses for {@link pagedExpand} continuously
+ * and invokes the callback registered for 'data' event for each element in the
+ * responses.
+ *
+ * The returned object has 'end' method when no more elements are required.
+ *
+ * autoPaginate option will be ignored.
+ *
+ * @see {@link https://nodejs.org/api/stream.html}
+ *
+ * @param {Object} request
+ *   The request object that will be sent.
+ * @param {string} request.content 
+ *   The string to expand.
+ * @param {number} request.page_size 
+ *   The amount of words to returned in each page.
+ * @param {string} request.page_token 
+ *   The position of the page to be returned.
+ * @param {object} [options]
+ *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+ * @returns {Stream}
+ *   An object stream which emits an object representing [EchoResponse]{@link google.showcase.v1beta1.EchoResponse} on 'data' event.
+ */
   pagedExpandStream(
       request?: protosTypes.google.showcase.v1beta1.IPagedExpandRequest,
       options?: gax.CallOptions | {}):