Bad JSdoc placement on Topic.setMetadata

[mgabeler-lee-6rs]

Thanks for stopping by to let us know something could be better!

If the support paths suggested above still do not result in a resolution, please provide the following details.

Environment details

• OS: Irrelevant
• Node.js version: Irrelevant
• npm version: Irrelevant
• @google-cloud/pubsub version: v2.5.0

Steps to reproduce

1. Install the latest version of @google-cloud/pubsub
2. Look for JSdoc for Topicl.setMetadata method
3. Sadness

There is JSdoc for this method in the source: https://github.com/googleapis/nodejs-pubsub/blob/master/src/topic.ts#L835

However, I believe it is placed incorrectly in relation to the overload declarations. Regardless, it is missing from the published .d.ts file:

    /**
     * In the event that the client fails to publish an ordered message, all
...
     */
    resumePublishing(orderingKey: string): void;
    setMetadata(options: TopicMetadata, gaxOpts?: CallOptions): Promise<SetTopicMetadataResponse>;
    setMetadata(options: TopicMetadata, callback: SetTopicMetadataCallback): void;
    setMetadata(options: TopicMetadata, gaxOpts: CallOptions, callback: SetTopicMetadataCallback): void;
    /**
     * Set the publisher options.
...

[feywind]

Thanks for the report! I'll add this to my list of docs/comments cleanup issues.

[feywind]

Actually, there are a bunch of them missing. There are a lot fewer that have JSDoc in the .d.ts that have them than the ones that don't. I wonder if something changed in the way the typings JSDoc is generated, because the generated HTML doc pages do actually have the comments.

[feywind]

This seems to be related: microsoft/TypeScript#25590

It seems TypeScript still doesn't want to support JavaScript style overloaded functions/methods. I'm going to flip this to a feature request, because I think it's going to take more effort to correct. :|

[feywind]

Hmm, the answer I'm getting seems to be: this isn't a great solution, but it's less bad than the other solutions we considered. TypeScript and JSDoc have a complicated relationship, apparently. It's intentional that we are just putting the comments into the generated .js files, but it does seem confusing to me that it's in the .d.ts for only some of the methods.

[feywind]

Moving this over here as a sort of wishlist item for now, since the overall answer I got from other folks working on GCP Node libraries was more or less "working as intended". I do think we'd like to improve it over time though.

[mgabeler-lee-6rs]

I'm confused as to how "writing API documentation that isn't visible to consumers of the API" is "working as intended"? Clearly I'm missing something here, as I'm sure that's not what is actually being suggested here :)