ACR docs improvements (#36989)

* acr docs --------- Co-authored-by: Vinay Gera <vigera@microsoft.com>
Azure · Nov 2, 2023 · 86b49ba · 86b49ba
1 parent 1f21d93
commit 86b49ba
Show file tree

Hide file tree

Showing 16 changed files with 786 additions and 502 deletions.
diff --git a/sdk/containerregistry/azure-containers-containerregistry/README.md b/sdk/containerregistry/azure-containers-containerregistry/README.md
@@ -5,9 +5,9 @@ Azure Container Registry allows you to store and manage container images and art
 Use the client library for Azure Container Registry to:
 
 - List images or artifacts in a registry
+- Upload, download, and delete images and artifacts, repositories and tags
 - Obtain metadata for images and artifacts, repositories and tags
 - Set read/write/delete properties on registry items
-- Delete images and artifacts, repositories and tags
 
 [Source code][source_code] | [Package (Maven)][package] | [Product documentation][product_docs] | [Samples][samples]
 
@@ -110,7 +110,7 @@ registryClient
 
 To authenticate with a registry in a [National Cloud](https://docs.microsoft.com/azure/active-directory/develop/authentication-national-cloud), you will need to make the following additions to your client configuration:
 - Set the `authorityHost` in the credential builder following [Identity client library documentation](https://learn.microsoft.com/java/api/overview/azure/identity-readme) 
-- If ACR access token authentication is disabled for yourcontainer Registry resource, you need to configure the audience on the Container Registry client builder.
+- If ACR access token authentication is disabled for your container Registry resource, you need to configure the audience on the Container Registry client builder.
 
 ```java readme-sample-armTokenChina
 ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
@@ -126,9 +126,10 @@ registryClient
 ```
 
 #### Anonymous access support
+
 If the builder is instantiated without any credentials, the SDK creates the service client for the anonymous pull mode.
 The user must use this setting on a registry that has been enabled for anonymous pull.
-In this mode, the user can only call listRepositoryNames method and its overload. All the other calls will fail. 
+In this mode, the user can only call `listRepositoryNames` method and its overload. All the other calls will fail. 
 For more information please read [Anonymous Pull Access](https://docs.microsoft.com/azure/container-registry/container-registry-faq#how-do-i-enable-anonymous-pull-access)
 
 ```java readme-sample-createAnonymousAccessClient
@@ -203,7 +204,6 @@ image.updateTagProperties(
         .setDeleteEnabled(false));
 ```
 
-
 #### Delete Images
 
 ```java readme-sample-deleteImages
@@ -270,10 +270,12 @@ To upload a full image, we need to upload individual layers and configuration. A
 which describes an image or artifact and assign it a tag.  
 
 ```java readme-sample-uploadImage
-BinaryData configContent = BinaryData.fromObject(Collections.singletonMap("hello", "world"));
+BinaryData configContent = BinaryData
+    .fromObject(Collections.singletonMap("hello", "world"));
 
 UploadRegistryBlobResult configUploadResult = contentClient.uploadBlob(configContent);
-System.out.printf("Uploaded config: digest - %s, size - %s\n", configUploadResult.getDigest(), configContent.getLength());
+System.out.printf("Uploaded config: digest - %s, size - %s\n", configUploadResult.getDigest(),
+    configContent.getLength());
 
 OciDescriptor configDescriptor = new OciDescriptor()
     .setMediaType("application/vnd.unknown.config.v1+json")
@@ -282,7 +284,8 @@ OciDescriptor configDescriptor = new OciDescriptor()
 
 BinaryData layerContent = BinaryData.fromString("Hello Azure Container Registry");
 UploadRegistryBlobResult layerUploadResult = contentClient.uploadBlob(layerContent);
-System.out.printf("Uploaded layer: digest - %s, size - %s\n", layerUploadResult.getDigest(), layerContent.getLength());
+System.out.printf("Uploaded layer: digest - %s, size - %s\n", layerUploadResult.getDigest(),
+    layerContent.getLength());
 
 OciImageManifest manifest = new OciImageManifest()
     .setConfiguration(configDescriptor)

diff --git a/...ry/src/main/java/com/azure/containers/containerregistry/ContainerRegistryAsyncClient.java b/...ry/src/main/java/com/azure/containers/containerregistry/ContainerRegistryAsyncClient.java
@@ -25,12 +25,21 @@
 import static com.azure.core.util.FluxUtil.withContext;
 
 /**
- * This class provides a client that exposes operations to managing container images and artifacts.
- * It exposes methods directly performed on the registry like listing the catalog.
- * as well as helper types like {@link #getArtifact(String, String) getArtifact} and {@link #getRepository(String) getRepository}
- * that can be used to perform operations on repository and artifacts directly.
+ * <p>This class provides a client that works with repositories in Azure Container Registry.
+ * It allows to list and delete repositories within the registry or obtain an instance of {@link ContainerRepositoryAsync}
+ * or {@link RegistryArtifactAsync} that can be used to perform operations on the repository or artifact.</p>
  *
- * <p><strong>Instantiating an asynchronous Container Registry client</strong></p>
+ * <h2>Getting Started</h2>
+ *
+ * <p>In order to interact with the Container Registry service you'll need to create an instance of
+ * ContainerRegistryAsyncClient.</p>
+ *
+ * <p>To create the client and communicate with the service, you'll need to use AAD authentication via
+ * <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable"> Azure Identity</a></p>.
+ *
+ * <p><strong>Sample: Construct Container Registry Async Client</strong></p>
+ *
+ * <p>The following code sample demonstrates the creation of a Container Registry Async Client.</p>
  *
  * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.instantiation -->
  * <pre>
@@ -41,23 +50,17 @@
  * </pre>
  * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.instantiation -->
  *
- * <p><strong>Instantiating an asynchronous Container Registry client using a custom pipeline</strong></p>
- * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.pipeline.instantiation -->
- * <pre>
- * HttpPipeline pipeline = new HttpPipelineBuilder&#40;&#41;
- *     .policies&#40;&#47;* add policies *&#47;&#41;
- *     .build&#40;&#41;;
+ * <p><strong>Note:</strong> For synchronous sample, refer to
+ * {@link com.azure.containers.containerregistry.ContainerRegistryClient}.</p>
  *
- * ContainerRegistryAsyncClient registryAsyncClient = new ContainerRegistryClientBuilder&#40;&#41;
- *     .pipeline&#40;pipeline&#41;
- *     .endpoint&#40;endpoint&#41;
- *     .credential&#40;credential&#41;
- *     .buildAsyncClient&#40;&#41;;
- * </pre>
- * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.pipeline.instantiation -->
+ * <p>View {@link ContainerRegistryClientBuilder} for additional ways to construct the client.</p>
  *
- * <p>View {@link ContainerRegistryClientBuilder this} for additional ways to construct the client.</p>
+ * <p>The Container Registry Async Client allows to list and delete repositories and obtain instances of repository and
+ * artifact client. See methods below to explore all capabilities this client provides.</p>
+
+ * <p>View {@link ContainerRegistryClientBuilder} for additional ways to construct the client.</p>
  *
+ * @see com.azure.containers.containerregistry
  * @see ContainerRegistryClientBuilder
  */
 @ServiceClient(builder = ContainerRegistryClientBuilder.class, isAsync = true)
@@ -77,8 +80,9 @@ public final class ContainerRegistryAsyncClient {
     }
 
     /**
-     * This method returns the complete registry endpoint.
-     * @return The registry endpoint including the authority.
+     *  Gets the service endpoint.
+     *
+     * @return The service endpoint for the Azure Container Registry instance.
      */
     public String getEndpoint() {
         return this.endpoint;
@@ -87,7 +91,7 @@ public String getEndpoint() {
     /**
      * List all the repository names in this registry.
      *
-     * <p><strong>List repository names in the registry.</strong></p>
+     * <p><strong>List repository names in the registry</strong></p>
      *
      * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.listRepositoryNames -->
      * <pre>
@@ -98,7 +102,7 @@ public String getEndpoint() {
      * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.listRepositoryNames -->
      *
      * @return list of repository names.
-     * @throws ClientAuthenticationException thrown if the client's credentials do not have access to modify the namespace.
+     * @throws ClientAuthenticationException thrown if the client's credentials do not have access to perform this operation.
      */
     @ServiceMethod(returns = ReturnType.COLLECTION)
     public PagedFlux<String> listRepositoryNames() {
@@ -125,9 +129,9 @@ private Mono<PagedResponse<String>> listRepositoryNamesNextSinglePageAsync(Strin
     }
 
     /**
-     * Delete the repository identified by 'repositoryName'.
+     * Delete the repository with provided {@code repositoryName}.
      *
-     * <p><strong>Delete a repository in the registry.</strong></p>
+     * <p><strong>Delete a repository in the registry</strong></p>
      *
      * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepositoryWithResponse#String -->
      * <pre>
@@ -139,11 +143,11 @@ private Mono<PagedResponse<String>> listRepositoryNamesNextSinglePageAsync(Strin
      * </pre>
      * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepositoryWithResponse#String -->
      *
-     * @param repositoryName Name of the repository (including the namespace).
+     * @param repositoryName Name of the repository.
      * @return the completion.
-     * @throws ClientAuthenticationException thrown if the client's credentials do not have access to modify the namespace.
+     * @throws ClientAuthenticationException thrown if the client's credentials do not have access to delete the repository.
      * @throws NullPointerException thrown if the {@code repositoryName} is null.
-     * @throws IllegalArgumentException thrown if the {@code repositoryName} is null.
+     * @throws IllegalArgumentException thrown if the {@code repositoryName} is empty.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<Response<Void>> deleteRepositoryWithResponse(String repositoryName) {
@@ -165,9 +169,9 @@ private Mono<Response<Void>> deleteRepositoryWithResponse(String repositoryName,
     }
 
     /**
-     * Delete the repository identified by {@code repositoryName}.
+     * Delete the repository with provided {@code repositoryName}.
      *
-     * <p><strong>Delete a repository in the registry.</strong></p>
+     * <p><strong>Delete a repository in the registry</strong></p>
      * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepository#String -->
      * <pre>
      * client.deleteRepository&#40;repositoryName&#41;.subscribe&#40;response -&gt; &#123;
@@ -178,9 +182,9 @@ private Mono<Response<Void>> deleteRepositoryWithResponse(String repositoryName,
      * </pre>
      * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepository#String -->
      *
-     * @param repositoryName Name of the image (including the namespace).
-     * @return the completion stream.
-     * @throws ClientAuthenticationException thrown if the client's credentials do not have access to modify the namespace.
+     * @param repositoryName Name of the repository.
+     * @return the completion.
+     * @throws ClientAuthenticationException thrown if the client's credentials do not have access to delete the repository.
      * @throws NullPointerException thrown if the {@code repositoryName} is null.
      * @throws IllegalArgumentException thrown if {@code repositoryName} is empty.
      */
@@ -196,7 +200,7 @@ private Mono<Void> deleteRepository(String repositoryName, Context context) {
     /**
      * Creates a new instance of {@link ContainerRepositoryAsync} object for the specified repository.
      *
-     * <p><strong>Create an instance of ContainerRepositoryAsync helper type</strong></p>
+     * <p><strong>Get an instance of {@link ContainerRepositoryAsync}</strong></p>
      * <!-- src_embed com.azure.containers.containerregistry.containeregistryasyncclient.getRepository -->
      * <pre>
      * ContainerRepositoryAsync repositoryAsync = client.getRepository&#40;repositoryName&#41;;
@@ -207,7 +211,7 @@ private Mono<Void> deleteRepository(String repositoryName, Context context) {
      * <!-- end com.azure.containers.containerregistry.containeregistryasyncclient.getRepository -->
      *
      * @param repositoryName Name of the repository to reference.
-     * @return A new {@link ContainerRepositoryAsync} for the desired repository.
+     * @return A new {@link ContainerRepositoryAsync} for the requested repository.
      * @throws NullPointerException if {@code repositoryName} is null.
      * @throws IllegalArgumentException if {@code repositoryName} is empty.
      */
@@ -218,7 +222,7 @@ public ContainerRepositoryAsync getRepository(String repositoryName) {
     /**
      * Creates a new instance of {@link RegistryArtifactAsync} object for the specified artifact.
      *
-     * <p><strong>Create an instance of RegistryArtifactAsync helper type</strong></p>
+     * <p><strong>Get an instance of {@link RegistryArtifactAsync}</strong></p>
      * <!-- src_embed com.azure.containers.containerregistry.containeregistryasyncclient.getArtifact -->
      * <pre>
      * RegistryArtifactAsync registryArtifactAsync = client.getArtifact&#40;repositoryName, tagOrDigest&#41;;
@@ -228,11 +232,11 @@ public ContainerRepositoryAsync getRepository(String repositoryName) {
      * </pre>
      * <!-- end com.azure.containers.containerregistry.containeregistryasyncclient.getArtifact -->
      *
-     * @param repositoryName Name of the repository to reference.
+     * @param repositoryName Name of the repository containing the artifact.
      * @param tagOrDigest Either a tag or digest that uniquely identifies the artifact.
-     * @return A new {@link RegistryArtifactAsync RegistryArtifactAsync} for the desired repository.
-     * @throws NullPointerException if {@code repositoryName} or {@code tagOrDigest} is null.
-     * @throws IllegalArgumentException if {@code repositoryName} or {@code tagOrDigest} is empty.
+     * @return A new {@link RegistryArtifactAsync RegistryArtifactAsync} for the requested artifact.
+     * @throws NullPointerException if {@code repositoryName} or {@code tagOrDigest} are null.
+     * @throws IllegalArgumentException if {@code repositoryName} or {@code tagOrDigest} are empty.
      */
     public RegistryArtifactAsync getArtifact(String repositoryName, String tagOrDigest) {
         return new RegistryArtifactAsync(repositoryName, tagOrDigest, httpPipeline, endpoint, apiVersion);