Skip to content

Commit

Permalink
fix: correct jsdoc for server streaming and pagination (#171)
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexander-fenster
alexander-fenster committed Dec 13, 2019
1 parent e71cb5c commit 3ec17f1
Show file tree
Hide file tree
Showing 5 changed files with 95 additions and 59 deletions.
23 changes: 16 additions & 7 deletions templates/typescript_gapic/_util.njk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ limitations under the License.
{%- elif method in service.paging %}
{{- printReturnPagingServerMethod(method) }}
{%- elif method.serverStreaming %}
{{- printReturnPagingServerMethod(method) }}
{{- printReturnServerStreamingMethod(method) }}
{%- elif method.clientStreaming %}
{{- printReturnClientStreamingMethod(method) }}
{%- else %}
Expand All @@ -119,17 +119,26 @@ limitations under the License.

{%- macro printReturnPagingServerMethod(method) %}
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing {{ typeLink(method.outputType) }}.
*
* The first element of the array is Array of {{ typeLink(method.pagingResponseType) }}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of {{ typeLink(method.outputType) }} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing {{ typeLink(method.outputType) }}.
* The first element is Array of {{ typeLink(method.pagingResponseType) }} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type {{ typeLink(method.inputType) }}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* {{ typeLink(method.outputType) }}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
{%- endmacro -%}

{%- macro printReturnServerStreamingMethod(method) %}
* @returns {Stream}
* An object stream which emits {{ typeLink(method.outputType) }} on 'data' event.
{%- endmacro -%}

{%- macro printReturnClientStreamingMethod(method) %}
* @returns {Stream} - A writable stream which accepts objects representing
Expand Down
68 changes: 44 additions & 24 deletions typescript/test/testdata/keymanager/src/v1/key_management_service_client.ts.baseline
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1567,13 +1567,18 @@ export class KeyManagementServiceClient {
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [ListKeyRingsResponse]{@link google.cloud.kms.v1.ListKeyRingsResponse}.
*
* The first element of the array is Array of [KeyRing]{@link google.cloud.kms.v1.KeyRing}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [ListKeyRingsResponse]{@link google.cloud.kms.v1.ListKeyRingsResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [ListKeyRingsResponse]{@link google.cloud.kms.v1.ListKeyRingsResponse}.
* The first element is Array of [KeyRing]{@link google.cloud.kms.v1.KeyRing} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type [ListKeyRingsRequest]{@link google.cloud.kms.v1.ListKeyRingsRequest}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* [ListKeyRingsResponse]{@link google.cloud.kms.v1.ListKeyRingsResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
*/
Expand Down Expand Up @@ -1701,13 +1706,18 @@ export class KeyManagementServiceClient {
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [ListCryptoKeysResponse]{@link google.cloud.kms.v1.ListCryptoKeysResponse}.
*
* The first element of the array is Array of [CryptoKey]{@link google.cloud.kms.v1.CryptoKey}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [ListCryptoKeysResponse]{@link google.cloud.kms.v1.ListCryptoKeysResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [ListCryptoKeysResponse]{@link google.cloud.kms.v1.ListCryptoKeysResponse}.
* The first element is Array of [CryptoKey]{@link google.cloud.kms.v1.CryptoKey} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type [ListCryptoKeysRequest]{@link google.cloud.kms.v1.ListCryptoKeysRequest}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* [ListCryptoKeysResponse]{@link google.cloud.kms.v1.ListCryptoKeysResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
*/
Expand Down Expand Up @@ -1838,13 +1848,18 @@ export class KeyManagementServiceClient {
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [ListCryptoKeyVersionsResponse]{@link google.cloud.kms.v1.ListCryptoKeyVersionsResponse}.
*
* The first element of the array is Array of [CryptoKeyVersion]{@link google.cloud.kms.v1.CryptoKeyVersion}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [ListCryptoKeyVersionsResponse]{@link google.cloud.kms.v1.ListCryptoKeyVersionsResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [ListCryptoKeyVersionsResponse]{@link google.cloud.kms.v1.ListCryptoKeyVersionsResponse}.
* The first element is Array of [CryptoKeyVersion]{@link google.cloud.kms.v1.CryptoKeyVersion} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type [ListCryptoKeyVersionsRequest]{@link google.cloud.kms.v1.ListCryptoKeyVersionsRequest}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* [ListCryptoKeyVersionsResponse]{@link google.cloud.kms.v1.ListCryptoKeyVersionsResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
*/
Expand Down Expand Up @@ -1973,13 +1988,18 @@ export class KeyManagementServiceClient {
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [ListImportJobsResponse]{@link google.cloud.kms.v1.ListImportJobsResponse}.
*
* The first element of the array is Array of [ImportJob]{@link google.cloud.kms.v1.ImportJob}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [ListImportJobsResponse]{@link google.cloud.kms.v1.ListImportJobsResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [ListImportJobsResponse]{@link google.cloud.kms.v1.ListImportJobsResponse}.
* The first element is Array of [ImportJob]{@link google.cloud.kms.v1.ImportJob} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type [ListImportJobsRequest]{@link google.cloud.kms.v1.ListImportJobsRequest}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* [ListImportJobsResponse]{@link google.cloud.kms.v1.ListImportJobsResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
*/
Expand Down
17 changes: 11 additions & 6 deletions typescript/test/testdata/redis/src/v1beta1/cloud_redis_client.ts.baseline
View file
Original file line number Diff line number Diff line change
Expand Up @@ -858,13 +858,18 @@ export class CloudRedisClient {
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [ListInstancesResponse]{@link google.cloud.redis.v1beta1.ListInstancesResponse}.
*
* The first element of the array is Array of [Instance]{@link google.cloud.redis.v1beta1.Instance}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [ListInstancesResponse]{@link google.cloud.redis.v1beta1.ListInstancesResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [ListInstancesResponse]{@link google.cloud.redis.v1beta1.ListInstancesResponse}.
* The first element is Array of [Instance]{@link google.cloud.redis.v1beta1.Instance} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type [ListInstancesRequest]{@link google.cloud.redis.v1beta1.ListInstancesRequest}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* [ListInstancesResponse]{@link google.cloud.redis.v1beta1.ListInstancesResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
*/
Expand Down
29 changes: 13 additions & 16 deletions typescript/test/testdata/showcase/src/v1beta1/echo_client.ts.baseline
View file
Original file line number Diff line number Diff line change
Expand Up @@ -337,16 +337,8 @@ export class EchoClient {
* The error that is thrown after all words are sent on the stream.
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [EchoResponse]{@link google.showcase.v1beta1.EchoResponse}.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [EchoResponse]{@link google.showcase.v1beta1.EchoResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [EchoResponse]{@link google.showcase.v1beta1.EchoResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
* @returns {Stream}
* An object stream which emits [EchoResponse]{@link google.showcase.v1beta1.EchoResponse} on 'data' event.
*/
expand(
request?: protosTypes.google.showcase.v1beta1.IExpandRequest,
Expand Down Expand Up @@ -503,13 +495,18 @@ export class EchoClient {
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [PagedExpandResponse]{@link google.showcase.v1beta1.PagedExpandResponse}.
*
* The first element of the array is Array of [EchoResponse]{@link google.showcase.v1beta1.EchoResponse}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [PagedExpandResponse]{@link google.showcase.v1beta1.PagedExpandResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [PagedExpandResponse]{@link google.showcase.v1beta1.PagedExpandResponse}.
* The first element is Array of [EchoResponse]{@link google.showcase.v1beta1.EchoResponse} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type [PagedExpandRequest]{@link google.showcase.v1beta1.PagedExpandRequest}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* [PagedExpandResponse]{@link google.showcase.v1beta1.PagedExpandResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
*/
Expand Down
17 changes: 11 additions & 6 deletions typescript/test/testdata/translate/src/v3beta1/translation_service_client.ts.baseline
View file
Original file line number Diff line number Diff line change
Expand Up @@ -932,13 +932,18 @@ export class TranslationServiceClient {
* @param {object} [options]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @returns {Promise} - The promise which resolves to an array.
* The first element of the array is an object representing [ListGlossariesResponse]{@link google.cloud.translation.v3beta1.ListGlossariesResponse}.
*
* The first element of the array is Array of [Glossary]{@link google.cloud.translation.v3beta1.Glossary}.
* The client library support auto-pagination by default: it will call the API as many
* times as needed and will merge results from all the pages into this array.
*
* When autoPaginate: false is specified through options, the array has three elements.
* The first element is Array of [ListGlossariesResponse]{@link google.cloud.translation.v3beta1.ListGlossariesResponse} in a single response.
* The second element is the next request object if the response
* indicates the next page exists, or null. The third element is
* an object representing [ListGlossariesResponse]{@link google.cloud.translation.v3beta1.ListGlossariesResponse}.
* The first element is Array of [Glossary]{@link google.cloud.translation.v3beta1.Glossary} that corresponds to
* the one page received from the API server.
* If the second element is not null it contains the request object of type [ListGlossariesRequest]{@link google.cloud.translation.v3beta1.ListGlossariesRequest}
* that can be used to obtain the next page of the results.
* If it is null, the next page does not exist.
* The third element contains the raw response received from the API server. Its type is
* [ListGlossariesResponse]{@link google.cloud.translation.v3beta1.ListGlossariesResponse}.
*
* The promise has a method named "cancel" which cancels the ongoing API call.
*/
Expand Down

0 comments on commit 3ec17f1

Please sign in to comment.