How in the world do I update a queue?

[JustinBeckwith]

So I'm actually trying to use @google-cloud/tasks, and I'm trying to call CloudTasksClient.updateQueue. The parameters for the request kinda don't make any sense. The IQueueUpdateRequest interface looks like this:

/** Properties of an UpdateQueueRequest. */
interface IUpdateQueueRequest {

    /** UpdateQueueRequest queue */
    queue?: (google.cloud.tasks.v2.IQueue|null);

    /** UpdateQueueRequest updateMask */
    updateMask?: (google.protobuf.IFieldMask|null);
}

The IQueue is an interface that describes the queue. I don't know if that's where I tell the API which queue I'm updating, or values I'm supposed to use. The IFieldMask interface appears to be a grab-bag of paths to update.

FWIW the apiary API is equally bad, and requires this field mask pattern. I'd like to do two things here:

• Dig into the API design, how it relates to libraries, and if we should change something (tagging @alexander-fenster for this)
• Add an updateQueue.js samples, which is curiously missing :) (tagging @averikitsch and @grant for this)

[alexander-fenster]

@JustinBeckwith In protos it says that you need to set the name field of the queue parameter to point it to the queue to be updated. I'm guessing you also set some other fields that you want to be updated, and list those fields in the field mask; fields not listed in the mask won't be touched.

I have some ideas how to make the proto comments available in the generated .d.ts files, I'll look into that.

https://github.com/googleapis/googleapis/blob/5340d28e386f4a70b6e9da146858b3f129b790a7/google/cloud/tasks/v2/cloudtasks.proto#L401-L416

// Request message for [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue].
message UpdateQueueRequest {
  // Required. The queue to create or update.
  //
  // The queue's [name][google.cloud.tasks.v2.Queue.name] must be specified.
  //
  // Output only fields cannot be modified using UpdateQueue.
  // Any value specified for an output only field will be ignored.
  // The queue's [name][google.cloud.tasks.v2.Queue.name] cannot be changed.
  Queue queue = 1 [(google.api.field_behavior) = REQUIRED];


  // A mask used to specify which fields of the queue are being updated.
  //
  // If empty, then all fields will be updated.
  google.protobuf.FieldMask update_mask = 2;
}

[averikitsch]

Hi @JustinBeckwith, thanks for adding an issue here. There is a buganizer issue floating around about how to update this for both Cloud Tasks and Scheduler. Feel free to message me if you want more background on why these samples haven't been added. Although, during the FixIt we tried to address this for Scheduler.

I agree the reference is not great but looking into it, it has changed multiple times. When we were actively working on these samples the docs looked much better. See here.

[alexander-fenster]

So first of all, it's not an external issue since @JustinBeckwith was a Googler when he created this :)

Then, apparently, the issue is basically about the lack of the field-level comments in the generated code and jsdoc. It's indeed bad. @summer-ji-eng and I will look into this in googleapis/gapic-generator-typescript#1129.

[averikitsch]

So first of all, it's not an external issue since @JustinBeckwith was a Googler when he created this :)

Then, apparently, the issue is basically about the lack of the field-level comments in the generated code and jsdoc. It's indeed bad. @summer-ji-eng and I will look into this in googleapis/gapic-generator-typescript#1129.

@alexander-fenster for the future, we use the label external as needing help from teams outside DPE, not that this was from an external collaborator. Please review the necessity of the comments you are leaving. Thanks!