docs: update jsdoc formatting and tests (#220)

googleapis · May 11, 2019 · 99ea91c · 99ea91c
1 parent 9c5282c
commit 99ea91c
Show file tree

Hide file tree

Showing 11 changed files with 92 additions and 76 deletions.
diff --git a/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/cloudtasks.proto b/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/cloudtasks.proto
@@ -19,12 +19,12 @@ package google.cloud.tasks.v2beta3;
 
 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/v2beta3/task.proto";
 import "google/cloud/tasks/v2beta3/queue.proto";
+import "google/cloud/tasks/v2beta3/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/v2beta3;tasks";
@@ -61,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: "/v2beta3/{parent=projects/*/locations/*}/queues"
@@ -82,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: "/v2beta3/{queue.name=projects/*/locations/*/queues/*}"
@@ -101,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: "/v2beta3/{name=projects/*/locations/*/queues/*}"
@@ -147,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: "/v2beta3/{name=projects/*/locations/*/queues/*}:resume"
@@ -293,7 +297,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".
   //
@@ -444,13 +449,14 @@ message ListTasksRequest {
   // permission on the [Task][google.cloud.tasks.v2beta3.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.v2beta3.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.v2beta3.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.

diff --git a/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/queue.proto b/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/queue.proto
@@ -157,11 +157,10 @@ message Queue {
   // time will be unset if the queue has never been purged.
   google.protobuf.Timestamp purge_time = 7;
 
-  // Specifies the fraction of operations to write to
-  // [Stackdriver Logging](https://cloud.google.com/logging/docs/).
-  // This field may contain any value between 0.0 and 1.0, inclusive.
-  // 0.0 is the default and means that no operations are logged.
-  double log_sampling_ratio = 10;
+  // Configuration options for writing logs to
+  // [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this
+  // field is unset, then no logs are written.
+  StackdriverLoggingConfig stackdriver_logging_config = 10;
 }
 
 // Rate limits.
@@ -341,3 +340,13 @@ message RetryConfig {
   // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters).
   int32 max_doublings = 5;
 }
+
+// Configuration options for writing logs to
+// [Stackdriver Logging](https://cloud.google.com/logging/docs/).
+message StackdriverLoggingConfig {
+  // Specifies the fraction of operations to write to
+  // [Stackdriver Logging](https://cloud.google.com/logging/docs/).
+  // This field may contain any value between 0.0 and 1.0, inclusive.
+  // 0.0 is the default and means that no operations are logged.
+  double sampling_ratio = 1;
+}
diff --git a/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/target.proto b/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/target.proto
@@ -128,7 +128,7 @@ message HttpRequest {
     // HTTP request.
     //
     // This type of authorization should be used when sending requests to third
-    // party endpoints.
+    // party endpoints or Cloud Run.
     OidcToken oidc_token = 6;
   }
 }
@@ -161,9 +161,6 @@ message AppEngineHttpQueue {
 // 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][google.cloud.tasks.v2beta3.Queue.app_engine_http_queue] set.
-//
 // Using [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest] requires
 // [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)
 // Google IAM permission for the project
@@ -426,7 +423,7 @@ message OAuthToken {
 // [OpenID Connect
 // token](https://developers.google.com/identity/protocols/OpenIDConnect). This
 // type of authorization should be used when sending requests to third party
-// endpoints.
+// endpoints or Cloud Run.
 message OidcToken {
   // [Service account email](https://cloud.google.com/iam/docs/service-accounts)
   // to be used for generating OIDC token.

diff --git a/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/task.proto b/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/task.proto
@@ -91,10 +91,6 @@ message Task {
 
     // HTTP request that is sent to the task's target.
     //
-    // Warning: This is an [alpha](https://cloud.google.com/terms/launch-stages)
-    // feature. If you haven't already joined, you can [use this form to sign
-    // up](https://docs.google.com/forms/d/e/1FAIpQLSfc4uEy9CBHKYUSdnY1hdhKDCX7julVZHy3imOiR-XrU7bUNQ/viewform).
-    //
     // An HTTP task is a task that has [HttpRequest][google.cloud.tasks.v2beta3.HttpRequest] set.
     HttpRequest http_request = 11;
   }

diff --git a/packages/google-cloud-tasks/src/v2beta3/cloud_tasks_client.js b/packages/google-cloud-tasks/src/v2beta3/cloud_tasks_client.js
@@ -236,7 +236,8 @@ class CloudTasksClient {
    *   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".
    *
@@ -361,7 +362,8 @@ class CloudTasksClient {
    *   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".
    *
@@ -471,8 +473,9 @@ class CloudTasksClient {
    * 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.
    *
    * @param {Object} request
    *   The request object that will be sent.
@@ -557,8 +560,9 @@ class CloudTasksClient {
    * 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.
    *
    * @param {Object} request
    *   The request object that will be sent.
@@ -637,8 +641,9 @@ class CloudTasksClient {
    * 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.
    *
    * @param {Object} request
    *   The request object that will be sent.
@@ -820,7 +825,8 @@ class CloudTasksClient {
    * 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).
    *
    * @param {Object} request
    *   The request object that will be sent.

diff --git a/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_cloudtasks.js b/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_cloudtasks.js
@@ -29,7 +29,8 @@
  *   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".
  *
@@ -262,13 +263,14 @@ const ResumeQueueRequest = {
  *   The number should be among the values of [View]{@link google.cloud.tasks.v2beta3.View}
  *
  * @property {number} pageSize
- *   Requested page size. Fewer tasks than requested might be returned.
+ *   Maximum page size.
  *
- *   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 in the
- *   response to determine if more tasks exist.
+ *   Fewer tasks than requested might be returned, even if more tasks exist; use
+ *   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.
  *
  * @property {string} pageToken
  *   A token identifying the page of results to return.

diff --git a/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_queue.js b/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_queue.js
@@ -116,11 +116,12 @@
  *
  *   This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp}
  *
- * @property {number} logSamplingRatio
- *   Specifies the fraction of operations to write to
- *   [Stackdriver Logging](https://cloud.google.com/logging/docs/).
- *   This field may contain any value between 0.0 and 1.0, inclusive.
- *   0.0 is the default and means that no operations are logged.
+ * @property {Object} stackdriverLoggingConfig
+ *   Configuration options for writing logs to
+ *   [Stackdriver Logging](https://cloud.google.com/logging/docs/). If this
+ *   field is unset, then no logs are written.
+ *
+ *   This object should have the same structure as [StackdriverLoggingConfig]{@link google.cloud.tasks.v2beta3.StackdriverLoggingConfig}
  *
  * @typedef Queue
  * @memberof google.cloud.tasks.v2beta3
@@ -378,4 +379,22 @@ const RateLimits = {
  */
 const RetryConfig = {
   // This is for documentation. Actual contents will be loaded by gRPC.
+};
+
+/**
+ * Configuration options for writing logs to
+ * [Stackdriver Logging](https://cloud.google.com/logging/docs/).
+ *
+ * @property {number} samplingRatio
+ *   Specifies the fraction of operations to write to
+ *   [Stackdriver Logging](https://cloud.google.com/logging/docs/).
+ *   This field may contain any value between 0.0 and 1.0, inclusive.
+ *   0.0 is the default and means that no operations are logged.
+ *
+ * @typedef StackdriverLoggingConfig
+ * @memberof google.cloud.tasks.v2beta3
+ * @see [google.cloud.tasks.v2beta3.StackdriverLoggingConfig definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/cloud/tasks/v2beta3/queue.proto}
+ */
+const StackdriverLoggingConfig = {
+  // This is for documentation. Actual contents will be loaded by gRPC.
 };
diff --git a/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_target.js b/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_target.js
@@ -120,7 +120,7 @@
  *   HTTP request.
  *
  *   This type of authorization should be used when sending requests to third
- *   party endpoints.
+ *   party endpoints or Cloud Run.
  *
  *   This object should have the same structure as [OidcToken]{@link google.cloud.tasks.v2beta3.OidcToken}
  *
@@ -171,9 +171,6 @@ const AppEngineHttpQueue = {
  * 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 set.
- *
  * Using AppEngineHttpRequest requires
  * [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control)
  * Google IAM permission for the project
@@ -437,7 +434,7 @@ const OAuthToken = {
  * [OpenID Connect
  * token](https://developers.google.com/identity/protocols/OpenIDConnect). This
  * type of authorization should be used when sending requests to third party
- * endpoints.
+ * endpoints or Cloud Run.
  *
  * @property {string} serviceAccountEmail
  *   [Service account email](https://cloud.google.com/iam/docs/service-accounts)

diff --git a/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_task.js b/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_task.js
@@ -50,10 +50,6 @@
  * @property {Object} httpRequest
  *   HTTP request that is sent to the task's target.
  *
- *   Warning: This is an [alpha](https://cloud.google.com/terms/launch-stages)
- *   feature. If you haven't already joined, you can [use this form to sign
- *   up](https://docs.google.com/forms/d/e/1FAIpQLSfc4uEy9CBHKYUSdnY1hdhKDCX7julVZHy3imOiR-XrU7bUNQ/viewform).
- *
  *   An HTTP task is a task that has HttpRequest set.
  *
  *   This object should have the same structure as [HttpRequest]{@link google.cloud.tasks.v2beta3.HttpRequest}

diff --git a/packages/google-cloud-tasks/synth.metadata b/packages/google-cloud-tasks/synth.metadata
@@ -1,5 +1,5 @@
 {
-  "updateTime": "2019-05-10T12:15:24.530722Z",
+  "updateTime": "2019-05-11T11:24:21.021732Z",
   "sources": [
     {
       "generator": {
@@ -12,8 +12,8 @@
       "git": {
         "name": "googleapis",
         "remote": "https://github.com/googleapis/googleapis.git",
-        "sha": "07883be5bf3c3233095e99d8e92b8094f5d7084a",
-        "internalRef": "247530843"
+        "sha": "32b08107fa1710f46287c17d5bb2016e443ed3ba",
+        "internalRef": "247684466"
       }
     },
     {