Update ACR Docstrings (Azure#22576)

* update docstrings

* more updates

* regen from updated swagger

* update generated API listing

* Update sdk/containerregistry/Azure.Containers.ContainerRegistry/src/ContainerRegistryClient.cs

Co-authored-by: Christopher Scott <[email protected]>

* Update sdk/containerregistry/Azure.Containers.ContainerRegistry/src/Repository/ContainerRepository.cs

Co-authored-by: Christopher Scott <[email protected]>

* pr fb

* update to latest swagger in azure-rest-api-specs repo

* export API

Co-authored-by: Christopher Scott <[email protected]>

Author: annelo-msft

sdk/containerregistry/Azure.Containers.ContainerRegistry/src/Artifact/RegistryArtifact.cs

@@ -9,7 +9,12 @@
 
 namespace Azure.Containers.ContainerRegistry
 {
-    /// <summary> A helper class that groups information and operations about an image or artifact in this container registry. </summary>
+    /// <summary> `Artifact` is the general term for items stored in a container registry,
+    /// and can include Docker images or other Open Container Initiative (OCI) artifact types.
+    /// <para>
+    /// The <see cref="RegistryArtifact"/> class is a helper class that groups information and operations about an image or artifact in this container registry.
+    /// </para>
+    /// </summary>
     public partial class RegistryArtifact
     {
         private readonly ClientDiagnostics _clientDiagnostics;
@@ -57,7 +62,7 @@ protected RegistryArtifact()
 
         #region Registry Artifact/Manifest methods
 
-        /// <summary> Get registry artifact properties by tag or digest. </summary>
+        /// <summary> Get the properties of the manifest that uniquely identifies this artifact. </summary>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
         public virtual async Task<Response<ArtifactManifestProperties>> GetManifestPropertiesAsync(CancellationToken cancellationToken = default)
@@ -77,7 +82,7 @@ public virtual async Task<Response<ArtifactManifestProperties>> GetManifestPrope
             }
         }
 
-        /// <summary> Get registry artifact properties by tag or digest. </summary>
+        /// <summary> Get the properties of the manifest that uniquely identifies this artifact. </summary>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
         public virtual Response<ArtifactManifestProperties> GetManifestProperties(CancellationToken cancellationToken = default)
@@ -118,8 +123,8 @@ private static bool IsDigest(string tagOrDigest)
             return tagOrDigest.Contains(":");
         }
 
-        /// <summary> Update manifest attributes. </summary>
-        /// <param name="value"> Manifest properties value. </param>
+        /// <summary> Update the properties of the artifact's manifest. </summary>
+        /// <param name="value"> Manifest properties object containing values to update. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="value"/> is null. </exception>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
@@ -141,8 +146,8 @@ public virtual async Task<Response<ArtifactManifestProperties>> UpdateManifestPr
             }
         }
 
-        /// <summary> Update manifest attributes. </summary>
-        /// <param name="value"> Manifest properties value. </param>
+        /// <summary> Update the properties of the artifact's manifest. </summary>
+        /// <param name="value"> Manifest properties object containing values to update. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="value"/> is null. </exception>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
@@ -177,7 +182,7 @@ private static ManifestWriteableProperties GetManifestWriteableProperties(Artifa
             };
         }
 
-        /// <summary> Delete registry artifact. </summary>
+        /// <summary> Delete registry artifact by deleting its manifest. </summary>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
         public virtual async Task<Response> DeleteAsync(CancellationToken cancellationToken = default)
@@ -196,7 +201,7 @@ public virtual async Task<Response> DeleteAsync(CancellationToken cancellationTo
             }
         }
 
-        /// <summary> Delete registry artifact. </summary>
+        /// <summary> Delete registry artifact by deleting its manifest. </summary>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
         public virtual Response Delete(CancellationToken cancellationToken = default)
@@ -218,7 +223,7 @@ public virtual Response Delete(CancellationToken cancellationToken = default)
         #endregion
 
         #region Tag methods
-        /// <summary> Get the collection of tags for a repository. </summary>
+        /// <summary> List the tags that uniquely identify this artifact and the properties of each. </summary>
         /// <param name="orderBy"> Requested order of tags in the collection. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
@@ -264,7 +269,7 @@ async Task<Page<ArtifactTagProperties>> NextPageFunc(string nextLink, int? pageS
             return PageableHelpers.CreateAsyncEnumerable(FirstPageFunc, NextPageFunc);
         }
 
-        /// <summary> Get the collection of tags for a repository, including their full metadata. </summary>
+        /// <summary> List the tags that uniquely identify this artifact and the properties of each. </summary>
         /// <param name="orderBy"> Requested order of tags in the collection. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
@@ -310,7 +315,7 @@ Page<ArtifactTagProperties> NextPageFunc(string nextLink, int? pageSizeHint)
             return PageableHelpers.CreateEnumerable(FirstPageFunc, NextPageFunc);
         }
 
-        /// <summary> Get tag properties by tag. </summary>
+        /// <summary> Get the properties of the specified tag. </summary>
         /// <param name="tag"> Tag name. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="tag"/> is null. </exception>
@@ -331,7 +336,7 @@ public virtual async Task<Response<ArtifactTagProperties>> GetTagPropertiesAsync
             }
         }
 
-        /// <summary> Get tag attributes by tag. </summary>
+        /// <summary> Get the properties of the specified tag. </summary>
         /// <param name="tag"> Tag name. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="tag"/> is null. </exception>
@@ -354,9 +359,9 @@ public virtual Response<ArtifactTagProperties> GetTagProperties(string tag, Canc
             }
         }
 
-        /// <summary> Update tag attributes. </summary>
-        /// <param name="tag"> Tag name. </param>
-        /// <param name="value"> Tag property value. </param>
+        /// <summary> Update the properties of a given tag. </summary>
+        /// <param name="tag"> Name of the tag to update properties on. </param>
+        /// <param name="value"> Tag properties object containing values to update. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="tag"/> is null. </exception>
         /// <exception cref="ArgumentException"> Thrown when <paramref name="tag"/> is empty. </exception>
@@ -391,9 +396,9 @@ private static TagWriteableProperties GetTagWriteableProperties(ArtifactTagPrope
             };
         }
 
-        /// <summary> Update tag attributes. </summary>
-        /// <param name="tag"> Tag name. </param>
-        /// <param name="value"> Tag property value. </param>
+        /// <summary> Update the properties of a given tag. </summary>
+        /// <param name="tag"> Name of the tag to update properties on. </param>
+        /// <param name="value"> Tag properties object containing values to update. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="tag"/> is null. </exception>
         /// <exception cref="ArgumentException"> Thrown when <paramref name="tag"/> is empty. </exception>
@@ -418,7 +423,7 @@ public virtual Response<ArtifactTagProperties> UpdateTagProperties(string tag, A
         }
 
         /// <summary> Delete the tag.  This removes the tag from the artifact and its manifest. </summary>
-        /// <param name="tag"> Name of tag to delete. </param>
+        /// <param name="tag"> The name of tag to delete. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="tag"/> is null. </exception>
         /// <exception cref="ArgumentException"> Thrown when <paramref name="tag"/> is empty. </exception>
@@ -441,7 +446,7 @@ public virtual async Task<Response> DeleteTagAsync(string tag, CancellationToken
         }
 
         /// <summary> Delete the tag.  This removes the tag from the artifact and its manifest. </summary>
-        /// <param name="tag"> Name of tag to delete. </param>
+        /// <param name="tag"> The name of tag to delete. </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="tag"/> is null. </exception>
         /// <exception cref="ArgumentException"> Thrown when <paramref name="tag"/> is empty. </exception>

sdk/containerregistry/Azure.Containers.ContainerRegistry/src/ContainerRegistryClient.cs

@@ -23,7 +23,7 @@ public partial class ContainerRegistryClient
         /// <summary>
         /// Initializes a new instance of the <see cref="ContainerRegistryClient"/> for managing container images and artifacts,
         /// using anonymous access to the registry.  Only operations that support anonymous access are enabled.  Other service
-        /// methods will throw <see cref="RequestFailedException"/> if called.
+        /// methods will throw <see cref="RequestFailedException"/> if called from this client.
         /// </summary>
         /// <param name="endpoint">The URI endpoint of the container registry.  This is likely to be similar
         /// to "https://{registry-name}.azurecr.io".</param>
@@ -33,9 +33,9 @@ public partial class ContainerRegistryClient
         }
 
         /// <summary>
-        /// Initializes a new instance of the ContainerRegistryClient for managing container images and artifacts,
+        /// Initializes a new instance of the <see cref="ContainerRegistryClient"/> for managing container images and artifacts,
         /// using anonymous access to the registry.  Only operations that support anonymous access are enabled.  Other service
-        /// methods will throw <see cref="RequestFailedException"/> if called.
+        /// methods will throw <see cref="RequestFailedException"/> if called from this client.
         /// </summary>
         /// <param name="endpoint">The URI endpoint of the container registry.  This is likely to be similar
         /// to "https://{registry-name}.azurecr.io".</param>
@@ -58,7 +58,7 @@ public partial class ContainerRegistryClient
         }
 
         /// <summary>
-        /// Initializes a new instance of the ContainerRegistryClient for managing container images and artifacts.
+        /// Initializes a new instance of the <see cref="ContainerRegistryClient"/> for managing container images and artifacts.
         /// </summary>
         /// <param name="endpoint">The URI endpoint of the container registry.  This is likely to be similar
         /// to "https://{registry-name}.azurecr.io".</param>
@@ -93,7 +93,7 @@ protected ContainerRegistryClient()
         /// </summary>
         public virtual Uri Endpoint => _endpoint;
 
-        /// <summary> List repositories in this registry. </summary>
+        /// <summary> List the names of the repositories in this registry. </summary>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
         public virtual AsyncPageable<string> GetRepositoryNamesAsync(CancellationToken cancellationToken = default)
@@ -134,7 +134,7 @@ async Task<Page<string>> NextPageFunc(string continuationToken, int? pageSizeHin
             return PageableHelpers.CreateAsyncEnumerable(FirstPageFunc, NextPageFunc);
         }
 
-        /// <summary> List repositories in this registry. </summary>
+        /// <summary> List the names of the repositories in this registry. </summary>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="RequestFailedException">Thrown when a failure is returned by the Container Registry service.</exception>
         public virtual Pageable<string> GetRepositoryNames(CancellationToken cancellationToken = default)
@@ -189,7 +189,7 @@ internal static string ParseUriReferenceFromLinkHeader(string linkValue)
             return linkValue?.Substring(1, linkValue.IndexOf('>') - 1);
         }
 
-        /// <summary> Delete the repository identified by `repostitory`. </summary>
+        /// <summary> Delete the repository identified by `repository` and all associated artifacts.</summary>
         /// <param name="repositoryName"> Repository name (including the namespace). </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="repositoryName"/> is null. </exception>
@@ -212,7 +212,7 @@ public virtual async Task<Response> DeleteRepositoryAsync(string repositoryName,
             }
         }
 
-        /// <summary> Delete the repository identified by `repostitory`. </summary>
+        /// <summary> Delete the repository identified by `repository` and all associated artifacts.</summary>
         /// <param name="repositoryName"> Repository name (including the namespace). </param>
         /// <param name="cancellationToken"> The cancellation token to use. </param>
         /// <exception cref="ArgumentNullException"> Thrown when <paramref name="repositoryName"/> is null. </exception>
@@ -236,7 +236,7 @@ public virtual Response DeleteRepository(string repositoryName, CancellationToke
         }
 
         /// <summary>
-        /// Create a new <see cref="ContainerRepository"/> object for the specified repository.
+        /// Create a new <see cref="ContainerRepository"/> object for calling service methods related to the repository specified by `repositoryName`.
         /// </summary>
         /// <param name="repositoryName"> The name of the repository to reference. </param>
         /// <returns> A new <see cref="ContainerRepository"/> for the desired repository. </returns>
@@ -254,7 +254,7 @@ public virtual ContainerRepository GetRepository(string repositoryName)
         }
 
         /// <summary>
-        /// Create a new <see cref="RegistryArtifact"/> object for the specified artifact.
+        /// Create a new <see cref="RegistryArtifact"/> object for calling service methods related to the artifact specified by `repositoryName` and `tagOrDigest`.
         /// </summary>
         /// <param name="repositoryName"> The name of the repository to reference. </param>
         /// <param name="tagOrDigest"> Either a tag or a digest that uniquely identifies the artifact. </param>

sdk/containerregistry/Azure.Containers.ContainerRegistry/src/ContainerRegistryClientOptions.cs

@@ -7,7 +7,7 @@
 namespace Azure.Containers.ContainerRegistry
 {
     /// <summary>
-    /// The options for <see cref="ContainerRegistryClient"/>
+    /// Options that allow users to configure the requests sent to the Container Registry service.
     /// </summary>
     public class ContainerRegistryClientOptions : ClientOptions
     {
@@ -25,6 +25,7 @@ public class ContainerRegistryClientOptions : ClientOptions
         public string AuthenticationScope { get; set; } = "https://management.azure.com/.default";
 
         /// <summary>
+        /// Create an instance of the options for configuring request sent to the Container Registry service.
         /// </summary>
         /// <param name="version"></param>
         public ContainerRegistryClientOptions(ServiceVersion version = ServiceVersion.V1_0)
@@ -49,6 +50,7 @@ private void AddHeadersAndQueryParameters()
         }
 
         /// <summary>
+        /// The versions of the Container Registry service supported by this client library.
         /// </summary>
         public enum ServiceVersion
         {