[Storage] Control `endpoint` function generation, generate pageable operation without `list` prefix

[vincenttran-msft]

Hi all, we are very very close and rounding the corner here, but here are our two asks that were generated as a result of the APIView review.

Control endpoint function generation

It appears that currently, because this is defined in the typespec:

@server(
  "{url}",
  "The host name of the blob storage account, e.g. accountName.blob.core.windows.net",
  {
    @doc("The host name of the blob storage account, e.g. accountName.blob.core.windows.net")
    url: url,
  }
)

Then we consequently get this generated on all our clients:

/// Returns the Url associated with this client.
    pub fn endpoint(&self) -> &Url {
        &self.endpoint
    }

Either way, we just want granular control as we possibly we like to not call this endpoint.

Generate pageable operation without list prefix

In this typespec PR: Azure/azure-rest-api-specs#42771

After doing the necessary work to make it a pageable operation (i.e. @list etc,), it now properly is a pageable operation, but now automatically prefixes the name with list:

pub async fn find_blobs_by_tags() -> pub fn list_find_blobs_by_tags()
(GitHub PR)
Is there anyway we could control this behavior?

Thanks 😄

[jhendrixMSFT]

At present, this naming is not configurable and comes from the Rust design guidelines. We could add mechanisms to customize them.

@heaths thoughts here?

[vincenttran-msft]

One possible solution here (tossed around in the Storage chat): Just a mechanism to hide endpoint() so we can just introduce what we want handwritten.

[heaths]

@jhendrixMSFT any way to detect if an explicit @@clientName was used on a member? If so, we could just say "use that" - even expecting they do the proper casing and all that to avoid any "magic".

@vincenttran-msft didn't you already hide endpoint before, or was that in the older hand-written clients? I'd be for a way to avoid generating it, though. We do have that @@clientOption do-everything decorator now.

[jhendrixMSFT]

Yep we can detect explicit @@clientName and use that verbatim to snake case (we do this elsewhere). I didn't want to run with that though until I was sure we're ok with deviating on the naming here.

[heaths]

I think it's fine in limited cases, though I ask that @vincenttran-msft et. al. reconsider find_ as a prefix. It's better than list_find_ certainly, but doesn't indicate it would return a pager (list). Perhaps list_matching_?

[jalauzon-msft]

I'd be for a way to avoid generating it

This would be great.

though I ask that @vincenttran-msft et. al. reconsider find_ as a prefix

I agree the name is not great and we considered a new one, but the REST API and all other languages use the naming scheme so figured it'd be best to leave the be consistent with our other products. Though if we feel strongly, I'm not opposed to list_blobs_by_tags or list_blobs_with_tags?

[heaths]

I don't feel strongly, no. While the name doesn't imply it returns a Pager, the type signature certainly will and with the type safety of Rust there's no mistaking it for something else.

[jhendrixMSFT]

I had a chat with @vincenttran-msft and it sounds like renaming will work here. I'd prefer this over omitting it as there might be utility in being able to rename it elsewhere. I don't feel strongly about this though, so if we think omitting is better then it works for me (both approaches are easy to implement in the emitter).

[jhendrixMSFT]

Hmm, renaming means you're stuck with the default doc comment.

/// Returns the Url associated with this client.

If that's not always correct, or you want to customize it, then adding an option to omit it is the correct solution.