Azure-sdk-for-js: [Storage Files] Can we please fix the documentation!

[gmantri]

• Package Name: @azure/storage-file-share
• Package Version: 12.3.0
• Operating system: macOS
• [x] nodejs
  
  
  
  • version: 10.16.3
  
  
• [ ] browser
  
  
  
  • name/version:
  
  
• [ ] typescript
  
  
  
  • version:
  
  
• Is the bug related to documentation in
  
  
  
  • [ ] README.md
  
  
  • [ ] source code documentation
  
  
  • [ ] SDK API docs on https://docs.microsoft.com
  
  

Describe the bug
A few examples:

Looking at the change log here: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/storage/storage-file-share/CHANGELOG.md.

Removed ability to create a ShareLeaseClient for a Share or Share Snapshot. This feature has been rescheduled for future release.

According to the release notes, I should not see ShareLeaseClient yet it is still there in both latest and preview.

Replaced ShareClient.setAccessTier() with ShareClient.setProperties(), which can be used to set both Share Tier and Share Quota.

Looking at the documentation for ShareClient again in both latest and preview, there's no setProperties() method. I can see setAccessTier() method and setQuota() method.

[ljian3377]

Thank you for the feedback. Will look into it. Meanwhile, you can use the API documentation on github.io for a better reference:
https://azure.github.io/azure-sdk-for-js/storage.html

The overview is reflecting the latest version but the API reference is stale.
@ramya-rao-a @maggiepint Do you know who should follow up on this?

[gmantri]

Thanks @ljian3377. Is it safe to assume that documentation on github.io will always be correct? If that's the case, can we change the link on npm to github.io?

[ljian3377]

We haven't found any issue with the github.io one so far. The doc team want to expose the official one though.

[gmantri]

Actually I just found one :). Github.io documentation is missing definition of ContainerUndeleteResponse.

[ramya-rao-a]

Hey there,

The azure.github.io docs website is our temporary solution to the problem of requiring API reference docs for multiple versions of the same package.

We do have automation in place to update the API reference docs at the docs.microsoft.com website which updates the docs in the week of the package release. We will look into why this was missed for the storage-file-share package.

Thanks for your patience!

[gmantri]

Hey there,

The azure.github.io docs website is our temporary solution to the problem of requiring API reference docs for multiple versions of the same package.

We do have automation in place to update the API reference docs at the docs.microsoft.com website which updates the docs in the week of the package release. We will look into why this was missed for the storage-file-share package.

Thanks for your patience!

I went to azure.github.io after a long time. What I really liked about that is I can browse through documentation for older versions of the SDK. This is kind of a big deal as not everyone will always migrate to newer version of the SDK as soon as it is released (ideally they should though) and would want to reference documentation of older versions of the SDK.

It would be incredibly awesome if Azure Docs also support that (I know that it is not going to be easy to implement but please consider it as a feature request).

[ljian3377]

Actually I just found one :). Github.io documentation is missing definition of ContainerUndeleteResponse.

Looks like it didn't work well with type alias ContainerRestoreResponse as ContainerUndeleteResponse,
https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-storage-blob/12.3.0/globals.html#containerrestoreresponse

https://docs.microsoft.com/en-gb/javascript/api/@azure/storage-blob/containerundeleteresponse?view=azure-node-latest
Official one shows it but not correctly for the _response field. 😢

[scbedd]

Hey @ljian3377 can I get a simpler description of what is wrong here?

This issue is filed with regard to @azure/storage-file-share, but the links posted just above are for @azure/storage-blob.

I just want to make certain I understand correctly. The documentation for @azure/storage-file-share still has an out of date function?

My understanding:

ShareLeaseClient shouldn't have setAccessTier() anymore. It should have setProperties() and other accompanying functions.

However when I dig into the documentation for ShareLeaseClient, I don't see either of those actually :(

Is this more a question of timing? @azure/storage-file-share does look fine to me right now (out of date wise).

[gmantri]

This issue is filed with regard to @azure/storage-file-share, but the links posted just above are for @azure/storage-blob.

@scbedd , that is probably my fault. Sorry about that! Basically storage blob came into picture as I started going through the documentation on azure.github.io. The primary question is about incorrect documentation for storage file share on Azure Docs site.

The documentation for @azure/storage-file-share still has an out of date function?

That's correct.

If you see my original post, the change log mentions that ShareLeaseClient has been dropped however the documentation still has that. Also ShareClient should not have setAccessTier and setQuota method (both of them are replaced by setProperties method). However the documentation still mentions both of these methods and does not mention setProperties method.

[ramya-rao-a]

However the documentation still mentions both of these methods and does not mention setProperties method.

This appears to be fixed now. The ShareClient does have setProperties method and there is no mention of setAccessTier anymore

If you see my original post, the change log mentions that ShareLeaseClient has been dropped however the documentation still has that.

The changelog says "Removed ability to create a ShareLeaseClient for a Share or Share Snapshot". I doubt if this means that ShareLeaseClient is dropped altogether... You can still get it from ShareFileClient.getShareLeaseClient() method. @ljian3377, Can you help clarify this?

[ljian3377]

@ramya-rao-a
The lease client for share is dropped but the lease client for file should still be there. So the existence of ShareFileClient.getShareLeaseClient() is expected. The changelog entry is misleading, my bad. Can we change the changelog now?

@scbedd
To summarize the issues mentioned in this post:

1. The delay of the update of the API reference doc. I checked it yesterday, it's still stale. We released on 2020-11-10, so here is a delay of more than one week. Is this expected?

2. The ContainerUndeleteResponse type is not showing correctly.
   https://docs.microsoft.com/en-gb/javascript/api/@azure/storage-blob/containerundeleteresponse?view=azure-node-latest

type ContainerUndeleteResponse = ContainerUndeleteHeaders & { _response: Object }

It should be

type ContainerRestoreResponse = ContainerRestoreHeaders & {
  _response: coreHttp.HttpResponse & {
      parsedHeaders: ContainerRestoreHeaders;
    };
};

This error is universal. Another example: https://docs.microsoft.com/en-gb/javascript/api/@azure/storage-blob/pageblobresizeresponse?view=azure-node-latest

1. Feature request - to support viewing API reference of any previous versions. Now we only have "preview" and "latest".

[ramya-rao-a]

@ljian3377 Yes, you can update the changelog now. You can also change the release info in https://github.com/Azure/azure-sdk-for-js/releases/tag/%40azure%2Fstorage-file-share_12.3.0

The problem with rendering ContainerUndeleteResponse where _response is typed as Object is a known issue that we have reported to the docs team already. I believe the docs team is also aware of the feature request for supporting previous API versions.

cc @diberry

[gmantri]

Thank you guys for looking into this and providing prompt responses. It is very much appreciated. I'll go ahead and close this issue now. Until next time :).

[ramya-rao-a]

Thanks for reporting @gmantri, we look forward to more feedback from you in the future :)