Move ACR to use the new code snippet generation. (#25372)

Move ACR to use the new code snippet generation.
Azure · Nov 15, 2021 · 7e0bcc9 · 7e0bcc9
1 parent 74fb8ab
commit 7e0bcc9
Show file tree

Hide file tree

Showing 10 changed files with 587 additions and 97 deletions.
diff --git a/sdk/containerregistry/azure-containers-containerregistry/README.md b/sdk/containerregistry/azure-containers-containerregistry/README.md
@@ -37,8 +37,7 @@ The [Azure Identity library][identity] provides easy Azure Active Directory supp
 Note all the below samples assume you have an endpoint, which is the URL including the name of the login server and the `https://` prefix.
 More information at [Azure Container Registry portal][container_registry_create_portal]
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L30-L35 -->
-```Java
+```java readme-sample-createClient
 DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
 ContainerRegistryClient client = new ContainerRegistryClientBuilder()
     .endpoint(endpoint)
@@ -47,8 +46,7 @@ ContainerRegistryClient client = new ContainerRegistryClientBuilder()
     .buildClient();
 ```
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L39-L44 -->
-```Java
+```java readme-sample-createAsyncClient
 DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
 ContainerRegistryAsyncClient client = new ContainerRegistryClientBuilder()
     .endpoint(endpoint)
@@ -64,12 +62,11 @@ To authenticate with a registry in a [National Cloud](https://docs.microsoft.com
 - Set the authorityHost in the credential builder.
 - Set the authenticationScope in ContainerRegistryClientBuilder.
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L193-L201 -->
-```Java
+```java readme-sample-nationalCloudSample
 ContainerRegistryClient containerRegistryClient = new ContainerRegistryClientBuilder()
     .endpoint(getEndpoint())
     .credential(credentials)
-    .audience(ContainerRegistryAudience.AZURECHINA)
+    .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_CHINA)
     .buildClient();
 
 containerRegistryClient
@@ -83,16 +80,14 @@ The user must use this setting on a registry that has been enabled for anonymous
 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)
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L76-L79 -->
-```Java
+```java readme-sample-createAnonymousAccessClient
 ContainerRegistryClient client = new ContainerRegistryClientBuilder()
     .endpoint(endpoint)
     .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
     .buildClient();
 ```
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L83-L86 -->
-```Java
+```java readme-sample-createAnonymousAsyncAccessClient
 ContainerRegistryAsyncClient client = new ContainerRegistryClientBuilder()
     .endpoint(endpoint)
     .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
@@ -127,8 +122,7 @@ For more information please see [Container Registry Concepts](https://docs.micro
 
 Iterate through the collection of repositories in the registry.
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L48-L55 -->
-```Java
+```java readme-sample-listRepositoryNames
 DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
 ContainerRegistryClient client = new ContainerRegistryClientBuilder()
     .endpoint(endpoint)
@@ -141,8 +135,7 @@ client.listRepositoryNames().forEach(repository -> System.out.println(repository
 
 ### List tags with anonymous access
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L147-L159 -->
-```Java
+```java readme-sample-listTagProperties
 ContainerRegistryClient anonymousClient = new ContainerRegistryClientBuilder()
     .endpoint(endpoint)
     .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
@@ -160,8 +153,7 @@ for (ArtifactTagProperties tag : tags) {
 
 ### Set artifact properties
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L125-L139 -->
-```Java
+```java readme-sample-setArtifactProperties
 TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
 
 ContainerRegistryClient client = new ContainerRegistryClientBuilder()
@@ -181,8 +173,7 @@ image.updateTagProperties(
 
 ### Delete Images
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L90-L119 -->
-```Java
+```java readme-sample-deleteImages
 TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
 
 ContainerRegistryClient client = new ContainerRegistryClientBuilder()
@@ -215,9 +206,8 @@ for (String repositoryName : client.listRepositoryNames()) {
 }
 ```
 
-### Delete repository with anonymous access throws 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L163-L176 -->
-```Java
+### Delete a repository with anonymous access throws
+```java readme-sample-anonymousClientThrows
 final String endpoint = getEndpoint();
 final String repositoryName = getRepositoryName();
 
@@ -239,8 +229,7 @@ try {
 All container registry service operations will throw a
 [HttpResponseException][HttpResponseException] on failure.
 
-<!-- embedme ./src/samples/java/com/azure/containers/containerregistry/ReadmeSamples.java#L61-L72 -->
-```Java
+```java readme-sample-getProperties
 DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
 ContainerRepository containerRepository = new ContainerRegistryClientBuilder()
     .endpoint(endpoint)

diff --git a/sdk/containerregistry/azure-containers-containerregistry/pom.xml b/sdk/containerregistry/azure-containers-containerregistry/pom.xml
@@ -28,6 +28,9 @@
   </scm>
 
   <properties>
+    <codesnippet.skip>false</codesnippet.skip>
+    <javadocDoclet></javadocDoclet>
+    <javadocDocletOptions></javadocDocletOptions>
     <!-- Configures the Java 9+ run to perform the required module exports, opens, and reads that are necessary for testing but shouldn't be part of the module-info. -->
     <javaModulesSurefireArgLine>
       --add-exports com.azure.core/com.azure.core.implementation.http=ALL-UNNAMED

diff --git a/...ry/src/main/java/com/azure/containers/containerregistry/ContainerRegistryAsyncClient.java b/...ry/src/main/java/com/azure/containers/containerregistry/ContainerRegistryAsyncClient.java
@@ -30,10 +30,31 @@
  *
  * <p><strong>Instantiating an asynchronous Container Registry client</strong></p>
  *
- * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryAsyncClient.instantiation}
+ * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.instantiation -->
+ * <pre>
+ * ContainerRegistryAsyncClient registryAsyncClient = new ContainerRegistryClientBuilder&#40;&#41;
+ *     .endpoint&#40;endpoint&#41;
+ *     .credential&#40;credential&#41;
+ *     .audience&#40;ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD&#41;
+ *     .buildAsyncClient&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.instantiation -->
  *
  * <p><strong>Instantiating an asynchronous Container Registry client using a custom pipeline</strong></p>
- * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryAsyncClient.pipeline.instantiation}
+ * <!-- 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;;
+ *
+ * ContainerRegistryAsyncClient registryAsyncClient = new ContainerRegistryClientBuilder&#40;&#41;
+ *     .pipeline&#40;pipeline&#41;
+ *     .endpoint&#40;endpoint&#41;
+ *     .audience&#40;ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD&#41;
+ *     .credential&#40;credential&#41;
+ *     .buildAsyncClient&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.pipeline.instantiation -->
  *
  * <p>View {@link ContainerRegistryClientBuilder this} for additional ways to construct the client.</p>
  *
@@ -74,7 +95,13 @@ public String getEndpoint() {
      *
      * <p><strong>List repository names in the registry.</strong></p>
      *
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryAsyncClient.listRepositoryNames}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.listRepositoryNames -->
+     * <pre>
+     * client.listRepositoryNames&#40;&#41;.subscribe&#40;name -&gt; &#123;
+     *     System.out.printf&#40;&quot;Repository Name:%s,&quot;, name&#41;;
+     * &#125;&#41;;
+     * </pre>
+     * <!-- 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.
@@ -122,7 +149,15 @@ Mono<PagedResponse<String>> listRepositoryNamesNextSinglePageAsync(String nextLi
      *
      * <p><strong>Delete a repository in the registry.</strong></p>
      *
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepositoryWithResponse#String}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepositoryWithResponse#String -->
+     * <pre>
+     * client.deleteRepositoryWithResponse&#40;repositoryName&#41;.subscribe&#40;response -&gt; &#123;
+     *     System.out.printf&#40;&quot;Successfully initiated delete of the repository.&quot;&#41;;
+     * &#125;, error -&gt; &#123;
+     *     System.out.println&#40;&quot;Failed to initiate a delete of the repository.&quot;&#41;;
+     * &#125;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepositoryWithResponse#String -->
      *
      * @param repositoryName Name of the repository (including the namespace).
      * @return the completion.
@@ -157,7 +192,15 @@ Mono<Response<Void>> deleteRepositoryWithResponse(String repositoryName, Context
      * Delete the repository identified by {@code repositoryName}.
      *
      * <p><strong>Delete a repository in the registry.</strong></p>
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepository#String}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepository#String -->
+     * <pre>
+     * client.deleteRepository&#40;repositoryName&#41;.subscribe&#40;response -&gt; &#123;
+     *     System.out.printf&#40;&quot;Successfully initiated delete of the repository.&quot;&#41;;
+     * &#125;, error -&gt; &#123;
+     *     System.out.println&#40;&quot;Failed to initiate a delete of the repository.&quot;&#41;;
+     * &#125;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryAsyncClient.deleteRepository#String -->
      *
      * @param repositoryName Name of the image (including the namespace).
      * @return the completion stream.
@@ -178,7 +221,14 @@ 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>
-     * {@codesnippet com.azure.containers.containerregistry.containeregistryasyncclient.getRepository}
+     * <!-- src_embed com.azure.containers.containerregistry.containeregistryasyncclient.getRepository -->
+     * <pre>
+     * ContainerRepositoryAsync repositoryAsync = client.getRepository&#40;repositoryName&#41;;
+     * repositoryAsync.getProperties&#40;&#41;.subscribe&#40;properties -&gt; &#123;
+     *     System.out.println&#40;properties.getName&#40;&#41;&#41;;
+     * &#125;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.containeregistryasyncclient.getRepository -->
      *
      * @param repositoryName Name of the repository to reference.
      * @return A new {@link ContainerRepositoryAsync} for the desired repository.
@@ -193,7 +243,14 @@ 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>
-     * {@codesnippet com.azure.containers.containerregistry.containeregistryasyncclient.getArtifact}
+     * <!-- src_embed com.azure.containers.containerregistry.containeregistryasyncclient.getArtifact -->
+     * <pre>
+     * RegistryArtifactAsync registryArtifactAsync = client.getArtifact&#40;repositoryName, tagOrDigest&#41;;
+     * registryArtifactAsync.getManifestProperties&#40;&#41;.subscribe&#40;properties -&gt; &#123;
+     *     System.out.println&#40;properties.getDigest&#40;&#41;&#41;;
+     * &#125;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.containeregistryasyncclient.getArtifact -->
      *
      * @param repositoryName Name of the repository to reference.
      * @param digest Either a tag or digest that uniquely identifies the artifact.

diff --git a/...egistry/src/main/java/com/azure/containers/containerregistry/ContainerRegistryClient.java b/...egistry/src/main/java/com/azure/containers/containerregistry/ContainerRegistryClient.java
@@ -18,10 +18,31 @@
  * that can be used to perform operations on repository and artifacts.
  *
  * <p><strong>Instantiating a synchronous Container Registry client</strong></p>
- * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.instantiation}
+ * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.instantiation -->
+ * <pre>
+ * ContainerRegistryClient registryAsyncClient = new ContainerRegistryClientBuilder&#40;&#41;
+ *     .endpoint&#40;endpoint&#41;
+ *     .audience&#40;ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD&#41;
+ *     .credential&#40;credential&#41;
+ *     .buildClient&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.instantiation -->
  *
  * <p><strong>Instantiating a synchronous Container Registry client with custom pipeline</strong></p>
- * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.pipeline.instantiation}
+ * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.pipeline.instantiation -->
+ * <pre>
+ * HttpPipeline pipeline = new HttpPipelineBuilder&#40;&#41;
+ *     .policies&#40;&#47;* add policies *&#47;&#41;
+ *     .build&#40;&#41;;
+ *
+ * ContainerRegistryClient registryAsyncClient = new ContainerRegistryClientBuilder&#40;&#41;
+ *     .pipeline&#40;pipeline&#41;
+ *     .endpoint&#40;endpoint&#41;
+ *     .audience&#40;ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD&#41;
+ *     .credential&#40;credential&#41;
+ *     .buildClient&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.pipeline.instantiation -->
  *
  * <p>View {@link ContainerRegistryClientBuilder this} for additional ways to construct the client.</p>
  *
@@ -48,7 +69,13 @@ public String getEndpoint() {
      *
      * <p><strong>List the repository names in the registry.</strong></p>
      *
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.listRepositoryNames}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.listRepositoryNames -->
+     * <pre>
+     * client.listRepositoryNames&#40;&#41;.stream&#40;&#41;.forEach&#40;name -&gt; &#123;
+     *     System.out.printf&#40;&quot;Repository Name:%s,&quot;, name&#41;;
+     * &#125;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.listRepositoryNames -->
      *
      * @return list of repository names.
      * @throws ClientAuthenticationException thrown if the client credentials do not have access to perform this operation.
@@ -62,7 +89,13 @@ public PagedIterable<String> listRepositoryNames() {
      * List all the repository names in this registry.
      *
      * <p><strong>List the repository names in the registry.</strong></p>
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.listRepositoryNames#Context}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.listRepositoryNames#Context -->
+     * <pre>
+     * client.listRepositoryNames&#40;Context.NONE&#41;.stream&#40;&#41;.forEach&#40;name -&gt; &#123;
+     *     System.out.printf&#40;&quot;Repository Name:%s,&quot;, name&#41;;
+     * &#125;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.listRepositoryNames#Context -->
      *
      * @param context The context to associate with this operation.
      * @return list of repositories.
@@ -77,7 +110,11 @@ public PagedIterable<String> listRepositoryNames(Context context) {
      * Delete the repository identified by {@code repositoryName}.
      *
      * <p><strong>Delete a repository in the registry.</strong></p>
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.deleteRepository#String}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.deleteRepository#String -->
+     * <pre>
+     * client.deleteRepository&#40;repositoryName&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.deleteRepository#String -->
      *
      * @param repositoryName Name of the repository (including the namespace).
      * @throws ClientAuthenticationException thrown if the client's credentials do not have access to modify the namespace.
@@ -93,7 +130,11 @@ public void deleteRepository(String repositoryName) {
      * Delete the repository identified by {@code repositoryName}.
      *
      *  <p><strong>Delete a repository in the registry.</strong></p>
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.deleteRepositoryWithResponse#String-Context}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.deleteRepositoryWithResponse#String-Context -->
+     * <pre>
+     * client.deleteRepositoryWithResponse&#40;repositoryName, Context.NONE&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.deleteRepositoryWithResponse#String-Context -->
      *
      * @param repositoryName Name of the repository (including the namespace).
      * @param context The context to associate with this operation.
@@ -111,7 +152,13 @@ public Response<Void> deleteRepositoryWithResponse(String repositoryName, Contex
      * Creates a new instance of {@link ContainerRepository} object for the specified repository.
      *
      *  <p><strong>Create a ContainerRegistry helper instance.</strong></p>
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.getRepository}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.getRepository -->
+     * <pre>
+     * ContainerRepository repository = client.getRepository&#40;repositoryName&#41;;
+     * ContainerRepositoryProperties properties = repository.getProperties&#40;&#41;;
+     * System.out.println&#40;properties.getName&#40;&#41;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.getRepository -->
      *
      * @param repositoryName Name of the repository to reference.
      * @return A new {@link ContainerRepository} for the desired repository.
@@ -126,7 +173,13 @@ public ContainerRepository getRepository(String repositoryName) {
      * Creates a new instance of {@link RegistryArtifact} object for the specified artifact.
      *
      *  <p><strong>Create a RegistryArtifact helper instance.</strong></p>
-     * {@codesnippet com.azure.containers.containerregistry.ContainerRegistryClient.getArtifact}
+     * <!-- src_embed com.azure.containers.containerregistry.ContainerRegistryClient.getArtifact -->
+     * <pre>
+     * RegistryArtifact registryArtifact = client.getArtifact&#40;repositoryName, tagOrDigest&#41;;
+     * ArtifactManifestProperties properties = registryArtifact.getManifestProperties&#40;&#41;;
+     * System.out.println&#40;properties.getDigest&#40;&#41;&#41;;
+     * </pre>
+     * <!-- end com.azure.containers.containerregistry.ContainerRegistryClient.getArtifact -->
      *
      *
      * @param repositoryName Name of the repository to reference.