docs: generate docs for ga release (#221)

Author: Benjamin E. Coe

packages/google-cloud-tasks/.repo-metadata.json

@@ -0,0 +1,13 @@
+{
+  "name": "tasks",
+  "name_pretty": "Cloud Tasks",
+  "product_documentation": "https://cloud.google.com/tasks/docs/",
+  "client_documentation": "https://cloud.google.com/nodejs/docs/reference/tasks/latest/",
+  "issue_tracker": "https://issuetracker.google.com/savedsearches/5433985",
+  "release_level": "ga",
+  "language": "nodejs",
+  "repo": "googleapis/nodejs-tasks",
+  "distribution_name": "@google-cloud/tasks",
+  "api_id": "tasks.googleapis.com",
+  "requires_billing": true
+}

packages/google-cloud-tasks/README.md

@@ -1,21 +1,22 @@
 [//]: # "This README.md file is auto-generated, all changes to this file will be lost."
-[//]: # "To regenerate it, use `npm run generate-scaffolding`."
+[//]: # "To regenerate it, use `python -m synthtool`."
 <img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>
 
-# [Google Cloud Tasks: Node.js Client](https://github.com/googleapis/nodejs-tasks)
+# [Cloud Tasks: Node.js Client](https://github.com/googleapis/nodejs-tasks)
 
-[![release level](https://img.shields.io/badge/release%20level-alpha-orange.svg?style&#x3D;flat)](https://cloud.google.com/terms/launch-stages)
+[![release level](https://img.shields.io/badge/release%20level-general%20availability%20%28GA%29-brightgreen.svg?style=flat)](https://cloud.google.com/terms/launch-stages)
 [![npm version](https://img.shields.io/npm/v/@google-cloud/tasks.svg)](https://www.npmjs.org/package/@google-cloud/tasks)
 [![codecov](https://img.shields.io/codecov/c/github/googleapis/nodejs-tasks/master.svg?style=flat)](https://codecov.io/gh/googleapis/nodejs-tasks)
 
-> Node.js idiomatic client for [Cloud Tasks][product-docs].
 
-Manages the execution of large numbers of distributed requests.
+
+
+Cloud Tasks API client for Node.js
 
 
 * [Cloud Tasks Node.js Client API Reference][client-docs]
-* [github.com/googleapis/nodejs-tasks](https://github.com/googleapis/nodejs-tasks)
 * [Cloud Tasks Documentation][product-docs]
+* [github.com/googleapis/nodejs-tasks](https://github.com/googleapis/nodejs-tasks)
 
 Read more about the client libraries for Cloud APIs, including the older
 Google APIs Client Libraries, in [Client Libraries Explained][explained].
@@ -24,69 +25,102 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
 
 **Table of contents:**
 
-* [Using the client library](#using-the-client-library)
+
+* [Quickstart](#quickstart)
+  * [Before you begin](#before-you-begin)
+  * [Installing the client library](#installing-the-client-library)
+  * [Using the client library](#using-the-client-library)
 * [Samples](#samples)
 * [Versioning](#versioning)
 * [Contributing](#contributing)
 * [License](#license)
 
-## Using the client library
+## Quickstart
 
-1.  [Select or create a Cloud Platform project][projects].
+### Before you begin
 
+1.  [Select or create a Cloud Platform project][projects].
 1.  [Enable billing for your project][billing].
-
-1.  [Enable the Google Cloud Tasks API][enable_api].
-
+1.  [Enable the Cloud Tasks API][enable_api].
 1.  [Set up authentication with a service account][auth] so you can access the
     API from your local workstation.
 
-1. Install the client library:
+### Installing the client library
+
+```bash
+npm install @google-cloud/tasks
+```
 
-        npm install --save @google-cloud/tasks
 
-1. Try an example:
+### Using the client library
 
-```js
-// Imports the Google Cloud client library
-const {CloudTasksClient} = require('@google-cloud/tasks');
+```javascript
+  // Imports the Google Cloud Tasks library.
+  const {CloudTasksClient} = require('@google-cloud/tasks');
 
-async function quickstart(
-  projectId = 'your-project-id', // Your Google Cloud Platform project ID
-  queue = 'my-appengine-queue', // Name of the Queue to create
-  location = 'us-central-1' // The region in which to create the queue
-) {
-  // Instantiates a client
+  // Instantiates a client.
   const client = new CloudTasksClient();
 
-  // Send create queue request.
-  const [response] = await client.createQueue({
-    // The fully qualified path to the location where the queue is created
-    parent: client.locationPath(projectId, location),
-    queue: {
-      // The fully qualified path to the queue
-      name: client.queuePath(projectId, location, queue),
-      appEngineHttpQueue: {
-        appEngineRoutingOverride: {
-          // The App Engine service that will receive the tasks.
-          service: 'default',
-        },
-      },
+  // TODO(developer): Uncomment these lines and replace with your values.
+  // const project = 'my-project-id';
+  // const queue = 'my-appengine-queue';
+  // const location = 'us-central1';
+  // const options = {payload: 'hello'};
+
+  // Construct the fully qualified queue name.
+  const parent = client.queuePath(project, location, queue);
+
+  const task = {
+    appEngineHttpRequest: {
+      httpMethod: 'POST',
+      relativeUri: '/log_payload',
     },
-  });
-  console.log(`Created queue ${response.name}`);
-}
+  };
+
+  if (payload) {
+    task.appEngineHttpRequest.body = Buffer.from(payload).toString('base64');
+  }
+
+  if (inSeconds) {
+    task.scheduleTime = {
+      seconds: inSeconds + Date.now() / 1000,
+    };
+  }
+
+  const request = {
+    parent: parent,
+    task: task,
+  };
+
+  console.log('Sending task:');
+  console.log(task);
+  // Send create task request.
+  const [response] = await client.createTask(request);
+  const name = response.name;
+  console.log(`Created task ${name}`);
+
+
 ```
 
+
+
 ## Samples
 
 Samples are in the [`samples/`](https://github.com/googleapis/nodejs-tasks/tree/master/samples) directory. The samples' `README.md`
 has instructions for running the samples.
 
 | Sample                      | Source Code                       | Try it |
 | --------------------------- | --------------------------------- | ------ |
-| Queues | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/createQueue.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/createQueue.js,samples/README.md) |
-| Tasks | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/createTask.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/createTask.js,samples/README.md) |
+| Create Http Task | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/createHttpTask.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/createHttpTask.js,samples/README.md) |
+| Create Http Task With Token | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/createHttpTaskWithToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/createHttpTaskWithToken.js,samples/README.md) |
+| Create Queue | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/createQueue.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/createQueue.js,samples/README.md) |
+| Create Task | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/createTask.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/createTask.js,samples/README.md) |
+| Delete Queue | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/deleteQueue.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/deleteQueue.js,samples/README.md) |
+| List Queues | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/listQueues.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/listQueues.js,samples/README.md) |
+| Quickstart | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) |
+| Server | [source code](https://github.com/googleapis/nodejs-tasks/blob/master/samples/server.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-tasks&page=editor&open_in_editor=samples/server.js,samples/README.md) |
+
+
 
 The [Cloud Tasks Node.js Client API Reference][client-docs] documentation
 also contains samples.
@@ -95,9 +129,16 @@ also contains samples.
 
 This library follows [Semantic Versioning](http://semver.org/).
 
-This library is considered to be in **alpha**. This means it is still a
-work-in-progress and under active development. Any release is subject to
-backwards-incompatible changes at any time.
+
+This library is considered to be **General Availability (GA)**. This means it
+is stable; the code surface will not change in backwards-incompatible ways
+unless absolutely necessary (e.g. because of critical security issues) or with
+an extensive deprecation period. Issues and requests against **GA** libraries
+are addressed with the highest priority.
+
+
+
+
 
 More Information: [Google Cloud Platform Launch Stages][launch_stages]
 
@@ -119,4 +160,4 @@ See [LICENSE](https://github.com/googleapis/nodejs-tasks/blob/master/LICENSE)
 [projects]: https://console.cloud.google.com/project
 [billing]: https://support.google.com/cloud/answer/6293499#enable-billing
 [enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=tasks.googleapis.com
-[auth]: https://cloud.google.com/docs/authentication/getting-started
+[auth]: https://cloud.google.com/docs/authentication/getting-started

packages/google-cloud-tasks/package.json

@@ -39,7 +39,7 @@
     "docs": "jsdoc -c .jsdoc.js",
     "system-test": "mocha system-test/ smoke-test/ --timeout 600000",
     "fix": "eslint '**/*.js' --fix",
-    "docs-test": "linkinator docs -r --skip www.googleapis.com",
+    "docs-test": "linkinator docs -r --skip 'www.googleapis.com|github.com/googleapis/nodejs-tasks/blob/master/samples/quickstart.js'",
     "predocs-test": "npm run docs"
   },
   "dependencies": {

packages/google-cloud-tasks/protos/google/cloud/tasks/v2/cloudtasks.proto

@@ -19,12 +19,12 @@ package google.cloud.tasks.v2;
 
 import "google/api/annotations.proto";
 import "google/api/resource.proto";
-import "google/protobuf/empty.proto";
-import "google/protobuf/field_mask.proto";
-import "google/cloud/tasks/v2/task.proto";
 import "google/cloud/tasks/v2/queue.proto";
+import "google/cloud/tasks/v2/task.proto";
 import "google/iam/v1/iam_policy.proto";
 import "google/iam/v1/policy.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
 import "google/rpc/code.proto";
 
 option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks";
@@ -33,7 +33,6 @@ option java_outer_classname = "CloudTasksProto";
 option java_package = "com.google.cloud.tasks.v2";
 option objc_class_prefix = "TASKS";
 
-
 // Cloud Tasks allows developers to manage the execution of background
 // work in their applications.
 service CloudTasks {
@@ -62,8 +61,9 @@ service CloudTasks {
   // WARNING: Using this method may have unintended side effects if you are
   // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.
   // Read
-  // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml)
-  // before using this method.
+  // [Overview of Queue Management and
+  // queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using
+  // this method.
   rpc CreateQueue(CreateQueueRequest) returns (Queue) {
     option (google.api.http) = {
       post: "/v2/{parent=projects/*/locations/*}/queues"
@@ -83,8 +83,9 @@ service CloudTasks {
   // WARNING: Using this method may have unintended side effects if you are
   // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.
   // Read
-  // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml)
-  // before using this method.
+  // [Overview of Queue Management and
+  // queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using
+  // this method.
   rpc UpdateQueue(UpdateQueueRequest) returns (Queue) {
     option (google.api.http) = {
       patch: "/v2/{queue.name=projects/*/locations/*/queues/*}"
@@ -102,8 +103,9 @@ service CloudTasks {
   // WARNING: Using this method may have unintended side effects if you are
   // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues.
   // Read
-  // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml)
-  // before using this method.
+  // [Overview of Queue Management and
+  // queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using
+  // this method.
   rpc DeleteQueue(DeleteQueueRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v2/{name=projects/*/locations/*/queues/*}"
@@ -148,7 +150,8 @@ service CloudTasks {
   // WARNING: Resuming many high-QPS queues at the same time can
   // lead to target overloading. If you are resuming high-QPS
   // queues, follow the 500/50/5 pattern described in
-  // [Managing Cloud Tasks Scaling Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling).
+  // [Managing Cloud Tasks Scaling
+  // Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling).
   rpc ResumeQueue(ResumeQueueRequest) returns (Queue) {
     option (google.api.http) = {
       post: "/v2/{name=projects/*/locations/*/queues/*}:resume"
@@ -230,8 +233,7 @@ service CloudTasks {
   //
   // Tasks cannot be updated after creation; there is no UpdateTask command.
   //
-  // * For [App Engine queues][google.cloud.tasks.v2.AppEngineHttpQueue], the maximum task size is
-  //   100KB.
+  // * The maximum task size is 100KB.
   rpc CreateTask(CreateTaskRequest) returns (Task) {
     option (google.api.http) = {
       post: "/v2/{parent=projects/*/locations/*/queues/*}/tasks"
@@ -294,7 +296,8 @@ message ListQueuesRequest {
   // field can be used as a filter and several operators as supported.
   // For example: `<=, <, >=, >, !=, =, :`. The filter syntax is the same as
   // described in
-  // [Stackdriver's Advanced Logs Filters](https://cloud.google.com/logging/docs/view/advanced_filters).
+  // [Stackdriver's Advanced Logs
+  // Filters](https://cloud.google.com/logging/docs/view/advanced_filters).
   //
   // Sample filter "state: PAUSED".
   //
@@ -445,13 +448,14 @@ message ListTasksRequest {
   // permission on the [Task][google.cloud.tasks.v2.Task] resource.
   Task.View response_view = 2;
 
-  // Requested page size. Fewer tasks than requested might be returned.
+  // Maximum page size.
+  //
+  // Fewer tasks than requested might be returned, even if more tasks exist; use
+  // [next_page_token][google.cloud.tasks.v2.ListTasksResponse.next_page_token] in the response to
+  // determine if more tasks exist.
   //
-  // The maximum page size is 1000. If unspecified, the page size will
-  // be the maximum. Fewer tasks than requested might be returned,
-  // even if more tasks exist; use
-  // [next_page_token][google.cloud.tasks.v2.ListTasksResponse.next_page_token] in the
-  // response to determine if more tasks exist.
+  // The maximum page size is 1000. If unspecified, the page size will be the
+  // maximum.
   int32 page_size = 3;
 
   // A token identifying the page of results to return.

packages/google-cloud-tasks/protos/google/cloud/tasks/v2/queue.proto

@@ -28,7 +28,6 @@ option java_multiple_files = true;
 option java_outer_classname = "QueueProto";
 option java_package = "com.google.cloud.tasks.v2";
 
-
 // A queue is a container of related tasks. Queues are configured to manage
 // how those tasks are dispatched. Configurable properties include rate limits,
 // retry options, queue types, and others.

packages/google-cloud-tasks/protos/google/cloud/tasks/v2/target.proto

@@ -24,15 +24,11 @@ option java_multiple_files = true;
 option java_outer_classname = "TargetProto";
 option java_package = "com.google.cloud.tasks.v2";
 
-
 // App Engine HTTP request.
 //
 // The message defines the HTTP request that is sent to an App Engine app when
 // the task is dispatched.
 //
-// This proto can only be used for tasks in a queue which has
-// [app_engine_http_queue][Queue.app_engine_http_queue] set.
-//
 // Using [AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest] requires
 // [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)
 // Google IAM permission for the project
@@ -78,13 +74,17 @@ option java_package = "com.google.cloud.tasks.v2";
 // required`](https://cloud.google.com/appengine/docs/standard/python/config/appref)
 // Task dispatches also do not follow redirects.
 //
-// The task attempt has succeeded if the app's request handler returns
-// an HTTP response code in the range [`200` - `299`]. `503` is
-// considered an App Engine system error instead of an application
-// error. Requests returning error `503` will be retried regardless of
-// retry configuration and not counted against retry counts.
-// Any other response code or a failure to receive a response before the
-// deadline is a failed attempt.
+// The task attempt has succeeded if the app's request handler returns an HTTP
+// response code in the range [`200` - `299`]. The task attempt has failed if
+// the app's handler returns a non-2xx response code or Cloud Tasks does
+// not receive response before the [deadline][google.cloud.tasks.v2.Task.dispatch_deadline]. Failed
+// tasks will be retried according to the
+// [retry configuration][Queue.RetryConfig]. `503` (Service Unavailable) is
+// considered an App Engine system error instead of an application error and
+// will cause Cloud Tasks' traffic congestion control to temporarily throttle
+// the queue's dispatches. Unlike other types of task targets, a `429` (Too Many
+// Requests) response from an app handler does not cause traffic congestion
+// control to throttle the queue.
 message AppEngineHttpRequest {
   // The HTTP method to use for the request. The default is POST.
   //

packages/google-cloud-tasks/protos/google/cloud/tasks/v2/task.proto

@@ -29,7 +29,6 @@ option java_multiple_files = true;
 option java_outer_classname = "TaskProto";
 option java_package = "com.google.cloud.tasks.v2";
 
-
 // A unit of scheduled work.
 message Task {
   // The view specifies a subset of [Task][google.cloud.tasks.v2.Task] data.

packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/cloudtasks.proto

@@ -233,8 +233,7 @@ service CloudTasks {
   //
   // Tasks cannot be updated after creation; there is no UpdateTask command.
   //
-  // * For [App Engine queues][google.cloud.tasks.v2beta3.AppEngineHttpQueue], the maximum task size is
-  //   100KB.
+  // * The maximum task size is 100KB.
   rpc CreateTask(CreateTaskRequest) returns (Task) {
     option (google.api.http) = {
       post: "/v2beta3/{parent=projects/*/locations/*/queues/*}/tasks"