[ACR] Docstring updates (Azure#22767)

* Sync update docstrings

* Updated model docstrings

* Async update docstrings

* Sync client docstring formatting

* Fix pylint

* Async client docstring

* Fix pylint

* Fix pylint

* Apply suggestions from code review

Co-authored-by: Yalin Li <[email protected]>

Co-authored-by: Yalin Li <[email protected]>

Author: annatisch

sdk/containerregistry/azure-containerregistry/azure/containerregistry/_container_registry_client.py

@@ -26,22 +26,22 @@
 class ContainerRegistryClient(ContainerRegistryBaseClient):
     def __init__(self, endpoint, credential=None, **kwargs):
         # type: (str, Optional[TokenCredential], **Any) -> None
-        """Create a ContainerRegistryClient from an ACR endpoint and a credential
+        """Create a ContainerRegistryClient from an ACR endpoint and a credential.
 
-        :param str endpoint: An ACR endpoint
-        :param credential: The credential with which to authenticate
+        :param str endpoint: An ACR endpoint.
+        :param credential: The credential with which to authenticate.
         :type credential: ~azure.core.credentials.TokenCredential
         :keyword api_version: API Version. The default value is "2021-07-01". Note that overriding this default value
-        may result in unsupported behavior.
+         may result in unsupported behavior.
         :paramtype api_version: str
         :keyword audience: URL to use for credential authentication with AAD. Its value could be
-        "https://management.azure.com", "https://management.chinacloudapi.cn", "https://management.microsoftazure.de" or
-        "https://management.usgovcloudapi.net"
+         "https://management.azure.com", "https://management.chinacloudapi.cn", "https://management.microsoftazure.de"
+         or "https://management.usgovcloudapi.net".
         :paramtype audience: str
         :returns: None
         :rtype: None
-        :raises ValueError: if the provided api_version keyword-only argument isn't supported or
-        audience keyword-only argument isn't provided
+        :raises ValueError: If the provided api_version keyword-only argument isn't supported or
+         audience keyword-only argument isn't provided.
 
         .. admonition:: Example:
 
@@ -590,14 +590,19 @@ def update_manifest_properties(self, repository, tag_or_digest, **kwargs):
     @distributed_trace
     def update_manifest_properties(self, *args, **kwargs):
         # type: (Union[str, ArtifactManifestProperties], **Any) -> ArtifactManifestProperties
-        """Set the properties for a manifest
+        """Set the permission properties for a manifest.
 
-        :param args:
-        :type args: Union[str, ~azure.containerregistry.ArtifactManifestProperties]
-        :param str repository: Repository the manifest belongs to
-        :param str tag_or_digest: Tag or digest of the manifest
-        :param properties: The property's values to be set
+        The updatable properties include: `can_delete`, `can_list`, `can_read`, and `can_write`.
+
+        :param str repository: Repository the manifest belongs to.
+        :param str tag_or_digest: Tag or digest of the manifest.
+        :param properties: The property's values to be set. This is a positional-only
+         parameter. Please provide either this or individual keyword parameters.
         :type properties: ~azure.containerregistry.ArtifactManifestProperties
+        :keyword bool can_delete: Delete permissions for a manifest.
+        :keyword bool can_list: List permissions for a manifest.
+        :keyword bool can_read: Read permissions for a manifest.
+        :keyword bool can_write: Write permissions for a manifest.
         :rtype: ~azure.containerregistry.ArtifactManifestProperties
         :raises: ~azure.core.exceptions.ResourceNotFoundError
 
@@ -659,14 +664,19 @@ def update_tag_properties(self, repository, tag, **kwargs):
     @distributed_trace
     def update_tag_properties(self, *args, **kwargs):
         # type: (Union[str, ArtifactTagProperties], **Any) -> ArtifactTagProperties
-        """Set the properties for a tag
-
-        :param args:
-        :type args: Union[str, ~azure.containerregistry.ArtifactTagProperties]
-        :param str repository: Repository the tag belongs to
-        :param str tag: Tag to set properties for
-        :param properties: The property's values to be set
-        :type properties: ArtifactTagProperties
+        """Set the permission properties for a tag.
+
+        The updatable properties include: `can_delete`, `can_list`, `can_read`, and `can_write`.
+
+        :param str repository: Repository the tag belongs to.
+        :param str tag: Tag to set properties for.
+        :param properties: The property's values to be set. This is a positional-only
+         parameter. Please provide either this or individual keyword parameters.
+        :type properties: ~azure.containerregistry.ArtifactTagProperties
+        :keyword bool can_delete: Delete permissions for a tag.
+        :keyword bool can_list: List permissions for a tag.
+        :keyword bool can_read: Read permissions for a tag.
+        :keyword bool can_write: Write permissions for a tag.
         :rtype: ~azure.containerregistry.ArtifactTagProperties
         :raises: ~azure.core.exceptions.ResourceNotFoundError
 
@@ -721,13 +731,18 @@ def update_repository_properties(self, repository, **kwargs):
     @distributed_trace
     def update_repository_properties(self, *args, **kwargs):
         # type: (Union[str, RepositoryProperties], **Any) -> RepositoryProperties
-        """Set the properties of a repository
+        """Set the permission properties of a repository.
 
-        :param args:
-        :type args: Union[str, ~azure.containerregistry.RepositoryProperties]
-        :param str repository: Name of the repository
-        :param properties: Properties to set for the repository
+        The updatable properties include: `can_delete`, `can_list`, `can_read`, and `can_write`.
+
+        :param str repository: Name of the repository.
+        :param properties: Properties to set for the repository. This is a positional-only
+         parameter. Please provide either this or individual keyword parameters.
         :type properties: ~azure.containerregistry.RepositoryProperties
+        :keyword bool can_delete: Delete permissions for a repository.
+        :keyword bool can_list: List permissions for a repository.
+        :keyword bool can_read: Read permissions for a repository.
+        :keyword bool can_write: Write permissions for a repository.
         :rtype: ~azure.containerregistry.RepositoryProperties
         :raises: ~azure.core.exceptions.ResourceNotFoundError
         """

sdk/containerregistry/azure-containerregistry/azure/containerregistry/_models.py

@@ -22,24 +22,24 @@
 
 
 class ArtifactManifestProperties(object):  # pylint: disable=too-many-instance-attributes
-    """Represents properties of a registry artifact
+    """Represents properties of a registry artifact.
 
-    :ivar bool can_delete: Delete Permissions for an artifact
-    :ivar bool can_write: Delete Permissions for an artifact
-    :ivar bool can_read: Delete Permissions for an artifact
-    :ivar bool can_list: Delete Permissions for an artifact
-    :ivar architecture: CPU Architecture of an artifact
+    :ivar bool can_delete: Delete Permissions for an artifact.
+    :ivar bool can_write: Write Permissions for an artifact.
+    :ivar bool can_read: Read Permissions for an artifact.
+    :ivar bool can_list: List Permissions for an artifact.
+    :ivar architecture: CPU Architecture of an artifact.
     :vartype architecture: ~azure.containerregistry.ArtifactArchitecture
-    :ivar created_on: Time and date an artifact was created
+    :ivar created_on: Time and date an artifact was created.
     :vartype created_on: ~datetime.datetime
-    :ivar str digest: Digest for the artifact
-    :ivar last_updated_on: Time and date an artifact was last updated
-    :vartype last_updated_on: datetime.datetime
-    :ivar operating_system: Operating system for the artifact
+    :ivar str digest: Digest for the artifact.
+    :ivar last_updated_on: Time and date an artifact was last updated.
+    :vartype last_updated_on: ~datetime.datetime
+    :ivar operating_system: Operating system for the artifact.
     :vartype operating_system: ~azure.containerregistry.ArtifactOperatingSystem
-    :ivar str repository_name: Repository name the artifact belongs to
-    :ivar str size_in_bytes: Size of the artifact
-    :ivar List[str] tags: Tags associated with a registry artifact
+    :ivar str repository_name: Repository name the artifact belongs to.
+    :ivar str size_in_bytes: Size of the artifact.
+    :ivar List[str] tags: Tags associated with a registry artifact.
     """
 
     def __init__(self, **kwargs):
@@ -150,19 +150,19 @@ def _to_generated(self):
 
 
 class RepositoryProperties(object):
-    """Model for storing properties of a single repository
+    """Represents properties of a single repository.
 
-    :ivar bool can_delete: Delete Permissions for an artifact
-    :ivar bool can_write: Delete Permissions for an artifact
-    :ivar bool can_read: Delete Permissions for an artifact
-    :ivar bool can_list: Delete Permissions for an artifact
+    :ivar bool can_delete: Delete Permissions for a repository.
+    :ivar bool can_write: Write Permissions for a repository.
+    :ivar bool can_read: Read Permissions for a repository.
+    :ivar bool can_list: List Permissions for a repository.
     :ivar created_on: Time the repository was created
-    :vartype created_on: datetime.datetime
-    :ivar last_updated_on: Time the repository was last updated
-    :vartype last_updated_on: datetime.datetime
-    :ivar int manifest_count: Number of manifest in the repository
-    :ivar str name: Name of the repository
-    :ivar int tag_count: Number of tags associated with the repository
+    :vartype created_on: ~datetime.datetime
+    :ivar last_updated_on: Time the repository was last updated.
+    :vartype last_updated_on: ~datetime.datetime
+    :ivar int manifest_count: Number of manifest in the repository.
+    :ivar str name: Name of the repository.
+    :ivar int tag_count: Number of tags associated with the repository.
     """
 
     def __init__(self, **kwargs):
@@ -227,19 +227,19 @@ def tag_count(self):
 
 
 class ArtifactTagProperties(object):
-    """Model for storing properties of a single tag
-
-    :ivar bool can_delete: Delete Permissions for an artifact
-    :ivar bool can_write: Delete Permissions for an artifact
-    :ivar bool can_read: Delete Permissions for an artifact
-    :ivar bool can_list: Delete Permissions for an artifact
-    :ivar created_on: Time the tag was created
-    :vartype created_on: datetime.datetime
-    :ivar str digest: Digest for the tag
-    :ivar last_updated_on: Time the tag was last updated
-    :vartype last_updated_on: datetime.datetime
-    :ivar str name: Name of the image the tag corresponds to
-    :ivar str repository: Repository the tag belongs to
+    """Represents properties of a single tag
+
+    :ivar bool can_delete: Delete Permissions for a tag.
+    :ivar bool can_write: Write Permissions for a tag.
+    :ivar bool can_read: Read Permissions for a tag.
+    :ivar bool can_list: List Permissions for a tag.
+    :ivar created_on: Time the tag was created.
+    :vartype created_on: ~datetime.datetime
+    :ivar str digest: Digest for the tag.
+    :ivar last_updated_on: Time the tag was last updated.
+    :vartype last_updated_on: ~datetime.datetime
+    :ivar str name: Name of the image the tag corresponds to.
+    :ivar str repository: Repository the tag belongs to.
     """
 
     def __init__(self, **kwargs):

sdk/containerregistry/azure-containerregistry/azure/containerregistry/aio/_async_container_registry_client.py

@@ -28,19 +28,22 @@
 class ContainerRegistryClient(ContainerRegistryBaseClient):
     def __init__(
         self, endpoint: str, credential: Optional["AsyncTokenCredential"] = None, *, audience, **kwargs: Any) -> None:
-        """Create a ContainerRegistryClient from an endpoint and a credential
+        """Create a ContainerRegistryClient from an ACR endpoint and a credential.
 
-        :param endpoint: An ACR endpoint
-        :type endpoint: str
-        :param credential: The credential with which to authenticate
+        :param str endpoint: An ACR endpoint.
+        :param credential: The credential with which to authenticate.
         :type credential: ~azure.core.credentials_async.AsyncTokenCredential
+        :keyword api_version: API Version. The default value is "2021-07-01". Note that overriding this default value
+         may result in unsupported behavior.
+        :paramtype api_version: str
         :keyword audience: URL to use for credential authentication with AAD. Its value could be
-        "https://management.azure.com", "https://management.chinacloudapi.cn", "https://management.microsoftazure.de" or
-        "https://management.usgovcloudapi.net"
-        :paramtype audience: ~azure.containerregistry.ContainerRegistryAudience or str
+         "https://management.azure.com", "https://management.chinacloudapi.cn", "https://management.microsoftazure.de"
+         or "https://management.usgovcloudapi.net".
+        :paramtype audience: str
         :returns: None
         :rtype: None
-        :raises: if the provided api_version keyword-only argument isn't supported
+        :raises ValueError: If the provided api_version keyword-only argument isn't supported or
+         audience keyword-only argument isn't provided.
 
         .. admonition:: Example:
 
@@ -581,13 +584,18 @@ def update_repository_properties(self, repository: str, **kwargs: Any) -> Reposi
     async def update_repository_properties(
         self, *args: Union[str, RepositoryProperties], **kwargs: Any
     ) -> RepositoryProperties:
-        """Set the properties of a repository
+        """Set the permission properties of a repository.
 
-        :param args:
-        :type args: Union[str, ~azure.containerregistry.RepositoryProperties]
-        :param str repository: Name of the repository
-        :param properties: Properties to set for the repository
+        The updatable properties include: `can_delete`, `can_list`, `can_read`, and `can_write`.
+
+        :param str repository: Name of the repository.
+        :param properties: Properties to set for the repository. This is a positional-only
+         parameter. Please provide either this or individual keyword parameters.
         :type properties: ~azure.containerregistry.RepositoryProperties
+        :keyword bool can_delete: Delete permissions for a repository.
+        :keyword bool can_list: List permissions for a repository.
+        :keyword bool can_read: Read permissions for a repository.
+        :keyword bool can_write: Write permissions for a repository.
         :rtype: ~azure.containerregistry.RepositoryProperties
         :raises: ~azure.core.exceptions.ResourceNotFoundError
         """
@@ -626,14 +634,19 @@ def update_manifest_properties(
     async def update_manifest_properties(
         self, *args: Union[str, ArtifactManifestProperties], **kwargs: Any
     ) -> ArtifactManifestProperties:
-        """Set the properties for a manifest
-
-        :param args:
-        :type args: Union[str, ~azure.containerregistry.ArtifactManifestProperties]
-        :param str repository: Name of the repository
-        :param str tag_or_digest: Tag or digest of the manifest
-        :param properties: The property's values to be set
-        :type properties: ArtifactManifestProperties
+        """Set the permission properties for a manifest.
+
+        The updatable properties include: `can_delete`, `can_list`, `can_read`, and `can_write`.
+
+        :param str repository: Repository the manifest belongs to.
+        :param str tag_or_digest: Tag or digest of the manifest.
+        :param properties: The property's values to be set. This is a positional-only
+         parameter. Please provide either this or individual keyword parameters.
+        :type properties: ~azure.containerregistry.ArtifactManifestProperties
+        :keyword bool can_delete: Delete permissions for a manifest.
+        :keyword bool can_list: List permissions for a manifest.
+        :keyword bool can_read: Read permissions for a manifest.
+        :keyword bool can_write: Write permissions for a manifest.
         :rtype: ~azure.containerregistry.ArtifactManifestProperties
         :raises: ~azure.core.exceptions.ResourceNotFoundError
 
@@ -696,14 +709,19 @@ def update_tag_properties(self, repository: str, tag: str, **kwargs: Any) -> Art
     async def update_tag_properties(
         self, *args: Union[str, ArtifactTagProperties], **kwargs: Any
     ) -> ArtifactTagProperties:
-        """Set the properties for a tag
-
-        :param args:
-        :type args: Union[str, ~azure.containerregistry.ArtifactTagProperties]
-        :param str repository: Repository the tag belongs to
-        :param str tag: Tag to set properties for
-        :param properties: The property's values to be set
-        :type properties: ArtifactTagProperties
+        """Set the permission properties for a tag.
+
+        The updatable properties include: `can_delete`, `can_list`, `can_read`, and `can_write`.
+
+        :param str repository: Repository the tag belongs to.
+        :param str tag: Tag to set properties for.
+        :param properties: The property's values to be set. This is a positional-only
+         parameter. Please provide either this or individual keyword parameters.
+        :type properties: ~azure.containerregistry.ArtifactTagProperties
+        :keyword bool can_delete: Delete permissions for a tag.
+        :keyword bool can_list: List permissions for a tag.
+        :keyword bool can_read: Read permissions for a tag.
+        :keyword bool can_write: Write permissions for a tag.
         :rtype: ~azure.containerregistry.ArtifactTagProperties
         :raises: ~azure.core.exceptions.ResourceNotFoundError