Docs updates (Azure#22453)

* Docs updates

* Undo changes to BlobsGetPropertiesHeaders

* pr feedback

Author: rickle-msft

sdk/storage/azure-storage-blob-cryptography/README.md

@@ -6,6 +6,8 @@ Unstructured data is data that does not adhere to a particular data model or
 definition, such as text or binary data.
 This package supports client side encryption for blob storage.
 
+[Source code][source] | [API reference documentation][docs] | [REST API documentation][rest_docs] | [Product documentation][product_docs] | [Samples][samples]
+
 ## Getting started
 
 ### Prerequisites
@@ -133,18 +135,20 @@ EncryptedBlobClient client = new EncryptedBlobClientBuilder()
 
 Create a `BlobServiceClient` using a connection string.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/specialized/cryptography/ReadmeSamples.java#L50-L54 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/specialized/cryptography/ReadmeSamples.java#L52-L58 -->
 ```java
 EncryptedBlobClient client = new EncryptedBlobClientBuilder()
     .key(key, keyWrapAlgorithm)
     .keyResolver(keyResolver)
     .connectionString(connectionString)
+    .containerName(containerName)
+    .blobName(blobName)
     .buildEncryptedBlobClient();
 ```
 
 ### Use a local `KeyEncryptionKey`
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/specialized/cryptography/ReadmeSamples.java#L58-L67 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/specialized/cryptography/ReadmeSamples.java#L62-L73 -->
 ```java
 JsonWebKey localKey = JsonWebKey.fromAes(new SecretKeySpec(keyBytes, secretKeyAlgorithm),
     Arrays.asList(KeyOperation.WRAP_KEY, KeyOperation.UNWRAP_KEY))
@@ -154,13 +158,16 @@ AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
 
 EncryptedBlobClient client = new EncryptedBlobClientBuilder()
     .key(akek, keyWrapAlgorithm)
+    .keyResolver(keyResolver)
     .connectionString(connectionString)
+    .containerName(containerName)
+    .blobName(blobName)
     .buildEncryptedBlobClient();
 ```
 
 ### Use a `KeyVaultKey`
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/specialized/cryptography/ReadmeSamples.java#L71-L86 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/specialized/cryptography/ReadmeSamples.java#L77-L94 -->
 ```java
 KeyClient keyClient = new KeyClientBuilder()
     .vaultUrl(keyVaultUrl)
@@ -176,7 +183,10 @@ AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
 
 EncryptedBlobClient client = new EncryptedBlobClientBuilder()
     .key(akek, keyWrapAlgorithm)
+    .keyResolver(keyResolver)
     .connectionString(connectionString)
+    .containerName(containerName)
+    .blobName(blobName)
     .buildEncryptedBlobClient();
 ```
 
@@ -209,6 +219,11 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fstorage%2Fazure-storage-blob-cryptography%2FREADME.png)
 
 [jdk]: https://docs.microsoft.com/java/azure/jdk/
+[source]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/storage/azure-storage-blob-cryptography/src
+[docs]: https://azure.github.io/azure-sdk-for-java/
+[rest_docs]: https://docs.microsoft.com/rest/api/storageservices/blob-service-rest-api
+[product_docs]: https://docs.microsoft.com/azure/storage/blobs/storage-blobs-overview
+[samples]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/storage/azure-storage-blob-cryptography/src/samples
 [azure_subscription]: https://azure.microsoft.com/free/
 [storage_account]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal
 [storage_account_create_cli]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli

sdk/storage/azure-storage-blob-cryptography/src/samples/java/com/azure/storage/blob/specialized/cryptography/ReadmeSamples.java

@@ -29,6 +29,8 @@ public class ReadmeSamples {
 
     private BlobClient blobClient;
     private String connectionString;
+    private String containerName;
+    private String blobName;
     private AsyncKeyEncryptionKey key;
     private AsyncKeyEncryptionKeyResolver keyResolver;
     private String keyWrapAlgorithm;
@@ -51,6 +53,8 @@ public void getEncryptedBlobClient() {
             .key(key, keyWrapAlgorithm)
             .keyResolver(keyResolver)
             .connectionString(connectionString)
+            .containerName(containerName)
+            .blobName(blobName)
             .buildEncryptedBlobClient();
     }
 
@@ -64,6 +68,8 @@ public void getClientLocalKey() {
         EncryptedBlobClient client = new EncryptedBlobClientBuilder()
             .key(akek, keyWrapAlgorithm)
             .connectionString(connectionString)
+            .containerName(containerName)
+            .blobName(blobName)
             .buildEncryptedBlobClient();
     }
 
@@ -83,9 +89,9 @@ public void getClientKeyVaultKey() {
         EncryptedBlobClient client = new EncryptedBlobClientBuilder()
             .key(akek, keyWrapAlgorithm)
             .connectionString(connectionString)
+            .containerName(containerName)
+            .blobName(blobName)
             .buildEncryptedBlobClient();
     }
-
-
 }
 

sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/models/BlobHttpHeaders.java

@@ -101,7 +101,8 @@ public BlobHttpHeaders setContentType(String contentType) {
 
     /**
      * Get the contentMd5 property: Optional. An MD5 hash of the blob content. Note that this hash is not validated, as
-     * the hashes for the individual blocks were validated when each was uploaded.
+     * the hashes for the individual blocks were validated when each was uploaded. The value does not need to be base64
+     * encoded as the SDK will perform the encoding.
      *
      * @return the contentMd5 value.
      */
@@ -111,7 +112,8 @@ public byte[] getContentMd5() {
 
     /**
      * Set the contentMd5 property: Optional. An MD5 hash of the blob content. Note that this hash is not validated, as
-     * the hashes for the individual blocks were validated when each was uploaded.
+     * the hashes for the individual blocks were validated when each was uploaded. The value does not need to be base64
+     * encoded as the SDK will perform the encoding.
      *
      * @param contentMd5 the contentMd5 value to set.
      * @return the BlobHttpHeaders object itself.

sdk/storage/azure-storage-blob/src/main/java/com/azure/storage/blob/models/BlobItem.java

@@ -65,7 +65,8 @@ public final class BlobItem {
     private List<ObjectReplicationPolicy> objectReplicationSourcePolicies;
 
     /*
-     * The isPrefix property.
+     * The isPrefix property. If blobs are named to mimic a directory hierarchy (i.e. path elements separated by a
+     * delimiter), this property may be used to determine if the {@code BlobItem} is a virtual directory.
      */
     @JsonProperty(value = "IsPrefix")
     private Boolean isPrefix;
@@ -254,7 +255,8 @@ public BlobItem setObjectReplicationSourcePolicies(List<ObjectReplicationPolicy>
     }
 
     /**
-     * Get the isPrefix property: The isPrefix property.
+     * Get the isPrefix property: If blobs are named to mimic a directory hierarchy (i.e. path elements separated by a
+     * delimiter), this property may be used to determine if the {@code BlobItem} is a virtual directory.
      *
      * @return the isPrefix value.
      */

sdk/storage/azure-storage-blob/swagger/src/main/java/com/azure/storage/blob/customization/BlobStorageCustomization.java

@@ -118,6 +118,14 @@ public void customize(LibraryCustomization customization) {
         ClassCustomization blobHttpHeaders = models.getClass("BlobHttpHeaders");
         blobHttpHeaders.removeAnnotation("@JacksonXmlRootElement(localName = \"BlobHttpHeaders\")");
         blobHttpHeaders.addAnnotation("@JacksonXmlRootElement(localName = \"blob-http-headers\")");
+        blobHttpHeaders.getMethod("getContentMd5").getJavadoc().setDescription("Get the contentMd5 property: " +
+            "Optional. An MD5 hash of the blob content. Note that this hash is not validated, as the hashes for " +
+            "the individual blocks were validated when each was uploaded. The value does not need to be base64 " +
+            "encoded as the SDK will perform the encoding.");
+        blobHttpHeaders.getMethod("setContentMd5").getJavadoc().setDescription("Set the contentMd5 property: " +
+            "Optional. An MD5 hash of the blob content. Note that this hash is not validated, as the hashes for " +
+            "the individual blocks were validated when each was uploaded. The value does not need to be base64 " +
+            "encoded as the SDK will perform the encoding.");
 
         ClassCustomization blobContainerEncryptionScope = models.getClass("BlobContainerEncryptionScope");
         blobContainerEncryptionScope.removeAnnotation("@JacksonXmlRootElement(localName = \"BlobContainerEncryptionScope\")");

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/DataLakeDirectoryAsyncClient.java

@@ -549,9 +549,9 @@ public PagedFlux<PathItem> listPaths() {
      * If "false", the values will be returned as Azure Active Directory Object IDs.
      * The default value is false. Note that group and application Object IDs are not translated because they do not
      * have unique friendly names.
-     * @param maxResults Specifies the maximum number of blobs to return, including all BlobPrefix elements. If the
-     * request does not specify maxResults or specifies a value greater than 5,000, the server will return up to
-     * 5,000 items.
+     * @param maxResults Specifies the maximum number of blobs to return per page, including all BlobPrefix elements. If
+     * the request does not specify maxResults or specifies a value greater than 5,000, the server will return up to
+     * 5,000 items per page.
      * @return A reactive response emitting the list of files/directories.
      */
     @ServiceMethod(returns = ReturnType.COLLECTION)

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/DataLakeDirectoryClient.java

@@ -476,10 +476,10 @@ public PagedIterable<PathItem> listPaths() {
      * If "false", the values will be returned as Azure Active Directory Object IDs.
      * The default value is false. Note that group and application Object IDs are not translated because they do not
      * have unique friendly names.
-     * @param maxResults Specifies the maximum number of blobs to return, including all BlobPrefix elements. If the
-     * request does not specify maxResults or specifies a value greater than 5,000, the server will return up to
-     * 5,000 items. If iterating by page, the page size passed to byPage methods such as
-     *      * {@link PagedIterable#iterableByPage(int)} will be preferred over this value.
+     * @param maxResults Specifies the maximum number of blobs to return per page, including all BlobPrefix elements. If
+     * the request does not specify maxResults or specifies a value greater than 5,000, the server will return up to
+     * 5,000 items per page. If iterating by page, the page size passed to byPage methods such as
+     * {@link PagedIterable#iterableByPage(int)} will be preferred over this value.
      * @param timeout An optional timeout value beyond which a {@link RuntimeException} will be raised.
      * @return The list of files/directories.
      */

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/models/ListPathsOptions.java

@@ -98,8 +98,9 @@ public ListPathsOptions setUserPrincipalNameReturned(boolean isUserPrincipalName
     }
 
     /**
-     * Specifies the maximum number of blobs to return, including all BlobPrefix elements. If the request does not
-     * specify maxResults or specifies a value greater than 5,000, the server will return up to 5,000 items.
+     * Specifies the maximum number of blobs to return per page, including all BlobPrefix elements. If the request does
+     * not specify maxResults or specifies a value greater than 5,000, the server will return up to 5,000 items per
+     * page.
      *
      * @return the number of containers to be returned in a single response
      */

sdk/storage/azure-storage-file-share/src/samples/java/com/azure/storage/file/share/ShareServiceJavaDocCodeSamples.java

@@ -115,7 +115,7 @@ public void createShareWithMetadata() {
         ShareServiceClient fileServiceClient = createClientWithSASToken();
         // BEGIN: ShareServiceClient.createShareWithResponse#string-map-integer-duration-context
         Response<ShareClient> response = fileServiceClient.createShareWithResponse("test",
-            Collections.singletonMap("share", "metadata"), null, Duration.ofSeconds(1),
+            Collections.singletonMap("share", "metadata"), null, Duration.ofSeconds(5),
             new Context(key1, value1));
         System.out.printf("Creating the share completed with status code %d", response.getStatusCode());
         // END: ShareServiceClient.createShareWithResponse#string-map-integer-duration-context
@@ -130,7 +130,7 @@ public void createShareWithOptions() {
         // BEGIN: ShareServiceClient.createShareWithResponse#String-ShareCreateOptions-Duration-Context
         Response<ShareClient> response = fileServiceClient.createShareWithResponse("test",
             new ShareCreateOptions().setMetadata(Collections.singletonMap("share", "metadata")).setQuotaInGb(1)
-            .setAccessTier(ShareAccessTier.HOT), Duration.ofSeconds(1), new Context(key1, value1));
+            .setAccessTier(ShareAccessTier.HOT), Duration.ofSeconds(5), new Context(key1, value1));
         System.out.printf("Creating the share completed with status code %d", response.getStatusCode());
         // END: ShareServiceClient.createShareWithResponse#String-ShareCreateOptions-Duration-Context
     }

sdk/storage/azure-storage-queue/src/samples/java/com/azure/storage/queue/ReadmeSamples.java

@@ -131,7 +131,7 @@ public void getQueueListInAccount() {
         // @param options: Filter for queue selection
         // @param timeout: An optional timeout applied to the operation.
         // @param context: Additional context that is passed through the Http pipeline during the service call.
-        queueServiceClient.listQueues(markers, options, timeout, context).stream().forEach(queueItem -> {
+        queueServiceClient.listQueues(options, timeout, context).stream().forEach(queueItem -> {
             System.out.printf("Queue %s exists in the account.", queueItem.getName());
         });
     }