Add REST API Documentation Links #4557
Conversation
* SAS implementation * Fixed some minor formatting issues * Fixed checkstyle problems and test issue
Removes RawClients from Storage Blobs
…to ContainerClient (Azure#4376) * Removed raw clients * Added deleteContainer to StorageClient * Added getAppendBlob with snapshot to ContainerClient
* Initial check in for storage queue
alzimmermsft
added
Storage
There was a problem hiding this comment.
Is the REST link better to put before code snippet? It is a reference for code description to me.
Is it better to have @see before the URL link?
https://docs.oracle.com/javase/6/docs/technotes/tools/windows/javadoc.html#@see
I would think of the link to the REST API documentation as further information beyond the method description and example, which would lead it to either be after the example or within a |
alzimmermsft
requested review from
christopheranderson,
conniey,
danieljurek,
g2vinay,
jaschrep-msft,
mitchdenny,
mssfang,
nemakam,
samvaity,
srnagar,
weshaggard,
yaohaizh and
yvgopal
as code owners
|
There are a lot of resource_manager files. Did you edit those too? 🤔 2157 files is a lot. lol |
| @@ -108,6 +108,9 @@ public URL getQueueUrl() { | |||
| * | |||
| * {@codesnippet com.azure.storage.queue.queueAsyncClient.create} | |||
| * | |||
| * <p>For more information, see the | |||
| * <a href="https://docs.microsoft.com/en-us/rest/api/storageservices/create-queue4">Azure Docs</a>.</p> | |||
There was a problem hiding this comment.
Instead of generic "Azure Docs", it's nice to see where this links to like: "Azure Docs: Create queue"
There was a problem hiding this comment.
Yup, even I think something like this "Azure Docs: Create queue" could be useful!
There was a problem hiding this comment.
+1, will this mean, that we will need to update the azure docs format in blob api too, to ensure consistency?
Was re-targeting the merge to go into master instead of a feature branch. |
alzimmermsft
removed request for
mitchdenny,
danieljurek,
christopheranderson,
g2vinay,
weshaggard,
yvgopal,
samvaity,
yaohaizh,
nemakam,
mssfang and
srnagar
| @@ -124,6 +127,9 @@ public URL getQueueUrl() { | |||
| * | |||
| * {@codesnippet com.azure.storage.queue.queueAsyncClient.create#map} | |||
| * | |||
| * <p>For more information, see the | |||
There was a problem hiding this comment.
Adding Rest docs link in javadocs,
Is this some standard guideline that all track 2 SDKs need to follow ?
Also, what happens when REST API docs link updates to a new version which doesn't correspond to our implemented SDK?
There was a problem hiding this comment.
This isn't a guideline for Track 2 SDKs, more of a nice to have feature given the depth of complexity in some of the Storage REST APIs. Additionally, Blobs has REST API doc links in previous versions and in Preview 1, so it is being consistent with it.
There was a problem hiding this comment.
@g2vinay in general, changes to our rest surface are only additive, and each parameter that was an addition at some point in time has a minimum version prominent in the description. If there is ever a breaking change to our rest surface, it is handled on a case by case basis. However, we don't diverge documentation pages. I would be impressed if one of these links became obsolete or problematic.
There was a problem hiding this comment.
Huh. So I'm looking into our links a bit more. It seems that we may break links, but I'm having trouble finding a scenario where we would direct you to the wrong one.
alzimmermsft
deleted the
AzStorage_Add_REST_Docs_Link_to_JavaDocs_in_Queues
branch
* Added links REST API documentation
Fixes #4496
Adds link to REST API documentation in the JavaDocs for Storage Queues.