Skip to content

Commit

Permalink
fix(docs): better jsdoc for generated libraries (#760)
Browse files Browse the repository at this point in the history 
* fix(docs): better jsdoc for generated libraries

* fix: pr feedback
  • Loading branch information
@alexander-fenster
alexander-fenster committed Nov 3, 2020
1 parent 1eff801 commit 1122522
Show file tree
Hide file tree
Showing 30 changed files with 2,983 additions and 7,887 deletions.
81 changes: 59 additions & 22 deletions baselines/asset/src/v1/asset_service_client.ts.baseline
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,10 @@ export class AssetServiceClient {
/**
* Construct an instance of AssetServiceClient.
*
* @param {object} [options] - The configuration object. See the subsequent
* parameters for more details.
* @param {object} [options] - The configuration object.
* The options accepted by the constructor are described in detail
* in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance).
* The common options are:
* @param {object} [options.credentials] - Credentials object.
* @param {string} [options.credentials.client_email]
* @param {string} [options.credentials.private_key]
Expand Down Expand Up @@ -81,7 +83,6 @@ export class AssetServiceClient {
* the fallback mode is enabled automatically; set `options.fallback` to `false`
* if you need to override this behavior.
*/

constructor(opts?: ClientOptions) {
// Ensure that options include all the required fields.
const staticMembers = this.constructor as typeof AssetServiceClient;
Expand Down Expand Up @@ -243,6 +244,7 @@ export class AssetServiceClient {

/**
* The DNS address for this API service.
* @returns {string} The DNS address for this service.
*/
static get servicePath() {
return 'cloudasset.googleapis.com';
Expand All @@ -251,13 +253,15 @@ export class AssetServiceClient {
/**
* The DNS address for this API service - same as servicePath(),
* exists for compatibility reasons.
* @returns {string} The DNS address for this service.
*/
static get apiEndpoint() {
return 'cloudasset.googleapis.com';
}

/**
* The port for this API service.
* @returns {number} The default port for this service.
*/
static get port() {
return 443;
Expand All @@ -266,6 +270,7 @@ export class AssetServiceClient {
/**
* The scopes needed to make gRPC calls for every method defined
* in this service.
* @returns {string[]} List of default scopes.
*/
static get scopes() {
return [
Expand All @@ -277,8 +282,7 @@ export class AssetServiceClient {
getProjectId(callback: Callback<string, undefined, undefined>): void;
/**
* Return the project ID used by this class.
* @param {function(Error, string)} callback - the callback to
* be called with the current project Id.
* @returns {Promise} A promise that resolves to string containing the project ID.
*/
getProjectId(callback?: Callback<string, undefined, undefined>):
Promise<string>|void {
Expand Down Expand Up @@ -351,7 +355,11 @@ export class AssetServiceClient {
* 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 [BatchGetAssetsHistoryResponse]{@link google.cloud.asset.v1.BatchGetAssetsHistoryResponse}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.batchGetAssetsHistory(request);
*/
batchGetAssetsHistory(
request: protos.google.cloud.asset.v1.IBatchGetAssetsHistoryRequest,
Expand Down Expand Up @@ -432,7 +440,11 @@ export class AssetServiceClient {
* 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 [Feed]{@link google.cloud.asset.v1.Feed}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.createFeed(request);
*/
createFeed(
request: protos.google.cloud.asset.v1.ICreateFeedRequest,
Expand Down Expand Up @@ -502,7 +514,11 @@ export class AssetServiceClient {
* 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 [Feed]{@link google.cloud.asset.v1.Feed}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.getFeed(request);
*/
getFeed(
request: protos.google.cloud.asset.v1.IGetFeedRequest,
Expand Down Expand Up @@ -571,7 +587,11 @@ export class AssetServiceClient {
* 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 [ListFeedsResponse]{@link google.cloud.asset.v1.ListFeedsResponse}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.listFeeds(request);
*/
listFeeds(
request: protos.google.cloud.asset.v1.IListFeedsRequest,
Expand Down Expand Up @@ -646,7 +666,11 @@ export class AssetServiceClient {
* 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 [Feed]{@link google.cloud.asset.v1.Feed}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.updateFeed(request);
*/
updateFeed(
request: protos.google.cloud.asset.v1.IUpdateFeedRequest,
Expand Down Expand Up @@ -716,7 +740,11 @@ export class AssetServiceClient {
* 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 [Empty]{@link google.protobuf.Empty}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.deleteFeed(request);
*/
deleteFeed(
request: protos.google.cloud.asset.v1.IDeleteFeedRequest,
Expand Down Expand Up @@ -807,8 +835,15 @@ export class AssetServiceClient {
* @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 [Operation]{@link google.longrunning.Operation}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* The first element of the array is an object representing
* a long running operation. Its `promise()` method returns a promise
* you can `await` for.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations)
* for more details and examples.
* @example
* const [operation] = await client.exportAssets(request);
* const [response] = await operation.promise();
*/
exportAssets(
request: protos.google.cloud.asset.v1.IExportAssetsRequest,
Expand Down Expand Up @@ -845,18 +880,19 @@ export class AssetServiceClient {
return this.innerApiCalls.exportAssets(request, options, callback);
}
/**
* Check the status of the long running operation returned by the exportAssets() method.
* Check the status of the long running operation returned by `exportAssets()`.
* @param {String} name
* The operation name that will be passed.
* @returns {Promise} - The promise which resolves to an object.
* The decoded operation object has result and metadata field to get information from.
*
* @example:
* const decodedOperation = await checkExportAssetsProgress(name);
* console.log(decodedOperation.result);
* console.log(decodedOperation.done);
* console.log(decodedOperation.metadata);
*
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations)
* for more details and examples.
* @example
* const decodedOperation = await checkExportAssetsProgress(name);
* console.log(decodedOperation.result);
* console.log(decodedOperation.done);
* console.log(decodedOperation.metadata);
*/
async checkExportAssetsProgress(name: string): Promise<LROperation<protos.google.cloud.asset.v1.ExportAssetsResponse, protos.google.cloud.asset.v1.ExportAssetsRequest>>{
const request = new operationsProtos.google.longrunning.GetOperationRequest({name});
Expand Down Expand Up @@ -977,9 +1013,10 @@ export class AssetServiceClient {
}

/**
* Terminate the GRPC channel and close the client.
* Terminate the gRPC channel and close the client.
*
* The client will no longer be usable and all future behavior is undefined.
* @returns {Promise} A promise that resolves when the client is closed.
*/
close(): Promise<void> {
this.initialize();
Expand Down
48 changes: 38 additions & 10 deletions baselines/bigquery-storage/src/v1beta1/big_query_storage_client.ts.baseline
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,10 @@ export class BigQueryStorageClient {
/**
* Construct an instance of BigQueryStorageClient.
*
* @param {object} [options] - The configuration object. See the subsequent
* parameters for more details.
* @param {object} [options] - The configuration object.
* The options accepted by the constructor are described in detail
* in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance).
* The common options are:
* @param {object} [options.credentials] - Credentials object.
* @param {string} [options.credentials.client_email]
* @param {string} [options.credentials.private_key]
Expand Down Expand Up @@ -82,7 +84,6 @@ export class BigQueryStorageClient {
* the fallback mode is enabled automatically; set `options.fallback` to `false`
* if you need to override this behavior.
*/

constructor(opts?: ClientOptions) {
// Ensure that options include all the required fields.
const staticMembers = this.constructor as typeof BigQueryStorageClient;
Expand Down Expand Up @@ -222,6 +223,7 @@ export class BigQueryStorageClient {

/**
* The DNS address for this API service.
* @returns {string} The DNS address for this service.
*/
static get servicePath() {
return 'bigquerystorage.googleapis.com';
Expand All @@ -230,13 +232,15 @@ export class BigQueryStorageClient {
/**
* The DNS address for this API service - same as servicePath(),
* exists for compatibility reasons.
* @returns {string} The DNS address for this service.
*/
static get apiEndpoint() {
return 'bigquerystorage.googleapis.com';
}

/**
* The port for this API service.
* @returns {number} The default port for this service.
*/
static get port() {
return 443;
Expand All @@ -245,6 +249,7 @@ export class BigQueryStorageClient {
/**
* The scopes needed to make gRPC calls for every method defined
* in this service.
* @returns {string[]} List of default scopes.
*/
static get scopes() {
return [
Expand All @@ -258,8 +263,7 @@ export class BigQueryStorageClient {
getProjectId(callback: Callback<string, undefined, undefined>): void;
/**
* Return the project ID used by this class.
* @param {function(Error, string)} callback - the callback to
* be called with the current project Id.
* @returns {Promise} A promise that resolves to string containing the project ID.
*/
getProjectId(callback?: Callback<string, undefined, undefined>):
Promise<string>|void {
Expand Down Expand Up @@ -336,7 +340,11 @@ export class BigQueryStorageClient {
* 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 [ReadSession]{@link google.cloud.bigquery.storage.v1beta1.ReadSession}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.createReadSession(request);
*/
createReadSession(
request: protos.google.cloud.bigquery.storage.v1beta1.ICreateReadSessionRequest,
Expand Down Expand Up @@ -411,7 +419,11 @@ export class BigQueryStorageClient {
* 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 [BatchCreateReadSessionStreamsResponse]{@link google.cloud.bigquery.storage.v1beta1.BatchCreateReadSessionStreamsResponse}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.batchCreateReadSessionStreams(request);
*/
batchCreateReadSessionStreams(
request: protos.google.cloud.bigquery.storage.v1beta1.IBatchCreateReadSessionStreamsRequest,
Expand Down Expand Up @@ -491,7 +503,11 @@ export class BigQueryStorageClient {
* 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 [Empty]{@link google.protobuf.Empty}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.finalizeStream(request);
*/
finalizeStream(
request: protos.google.cloud.bigquery.storage.v1beta1.IFinalizeStreamRequest,
Expand Down Expand Up @@ -578,7 +594,11 @@ export class BigQueryStorageClient {
* 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 [SplitReadStreamResponse]{@link google.cloud.bigquery.storage.v1beta1.SplitReadStreamResponse}.
* The promise has a method named "cancel" which cancels the ongoing API call.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods)
* for more details and examples.
* @example
* const [response] = await client.splitReadStream(request);
*/
splitReadStream(
request: protos.google.cloud.bigquery.storage.v1beta1.ISplitReadStreamRequest,
Expand Down Expand Up @@ -636,6 +656,13 @@ export class BigQueryStorageClient {
* 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 [ReadRowsResponse]{@link google.cloud.bigquery.storage.v1beta1.ReadRowsResponse} on 'data' event.
* Please see the
* [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#server-streaming)
* for more details and examples.
* @example
* const stream = client.readRows(request);
* stream.on('data', (response) => { ... });
* stream.on('end', () => { ... });
*/
readRows(
request?: protos.google.cloud.bigquery.storage.v1beta1.IReadRowsRequest,
Expand Down Expand Up @@ -757,9 +784,10 @@ export class BigQueryStorageClient {
}

/**
* Terminate the GRPC channel and close the client.
* Terminate the gRPC channel and close the client.
*
* The client will no longer be usable and all future behavior is undefined.
* @returns {Promise} A promise that resolves when the client is closed.
*/
close(): Promise<void> {
this.initialize();
Expand Down
Loading

0 comments on commit 1122522

Please sign in to comment.