core doc fixes (Azure#38878)

xiangyan99 · web-flow · commit bd605d95ef92 · 2024-12-14T09:48:48.000-08:00
* core doc fixes

* update

* update

* update

* update
diff --git a/sdk/core/azure-core/azure/core/credentials.py b/sdk/core/azure-core/azure/core/credentials.py
@@ -147,7 +147,7 @@ class AzureKeyCredential:
     It provides the ability to update the key without creating a new client.
 
     :param str key: The key used to authenticate to an Azure service
-    :raises: TypeError
+    :raises TypeError: If the key is not a string.
     """
 
     def __init__(self, key: str) -> None:
@@ -185,7 +185,7 @@ class AzureSasCredential:
     It provides the ability to update the shared access signature without creating a new client.
 
     :param str signature: The shared access signature used to authenticate to an Azure service
-    :raises: TypeError
+    :raises TypeError: If the signature is not a string.
     """
 
     def __init__(self, signature: str) -> None:
@@ -209,7 +209,8 @@ def update(self, signature: str) -> None:
         to update long-lived clients.
 
         :param str signature: The shared access signature used to authenticate to an Azure service
-        :raises: ValueError or TypeError
+        :raises ValueError: If the signature is None or empty.
+        :raises TypeError: If the signature is not a string.
         """
         if not signature:
             raise ValueError("The signature used for updating can not be None or empty")
@@ -224,7 +225,7 @@ class AzureNamedKeyCredential:
 
     :param str name: The name of the credential used to authenticate to an Azure service.
     :param str key: The key used to authenticate to an Azure service.
-    :raises: TypeError
+    :raises TypeError: If the name or key is not a string.
     """
 
     def __init__(self, name: str, key: str) -> None:
diff --git a/sdk/core/azure-core/azure/core/pipeline/_tools.py b/sdk/core/azure-core/azure/core/pipeline/_tools.py
@@ -44,7 +44,7 @@ def await_result(func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
     :type args: list
     :rtype: any
     :return: The result of the function
-    :raises: TypeError
+    :raises TypeError: If the function returns an awaitable object.
     """
     result = func(*args, **kwargs)
     if hasattr(result, "__await__"):
diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_authentication.py b/sdk/core/azure-core/azure/core/pipeline/policies/_authentication.py
@@ -116,7 +116,7 @@ class BearerTokenCredentialPolicy(_BearerTokenCredentialPolicyBase, HTTPPolicy[H
     :param str scopes: Lets you specify the type of access needed.
     :keyword bool enable_cae: Indicates whether to enable Continuous Access Evaluation (CAE) on all requested
         tokens. Defaults to False.
-    :raises: :class:`~azure.core.exceptions.ServiceRequestError`
+    :raises ~azure.core.exceptions.ServiceRequestError: If the request fails.
     """
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
@@ -245,7 +245,8 @@ class AzureKeyCredentialPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseTyp
     :type credential: ~azure.core.credentials.AzureKeyCredential
     :param str name: The name of the key header used for the credential.
     :keyword str prefix: The name of the prefix for the header value if any.
-    :raises: ValueError or TypeError
+    :raises ValueError: if name is None or empty.
+    :raises TypeError: if name is not a string or if credential is not an instance of AzureKeyCredential.
     """
 
     def __init__(  # pylint: disable=unused-argument
@@ -276,7 +277,7 @@ class AzureSasCredentialPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseTyp
 
     :param credential: The credential used to authenticate requests.
     :type credential: ~azure.core.credentials.AzureSasCredential
-    :raises: ValueError or TypeError
+    :raises ValueError: if credential is None.
     """
 
     def __init__(
diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_authentication_async.py b/sdk/core/azure-core/azure/core/pipeline/policies/_authentication_async.py
@@ -61,7 +61,7 @@ async def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
 
         :param request: The pipeline request object to be modified.
         :type request: ~azure.core.pipeline.PipelineRequest
-        :raises: :class:`~azure.core.exceptions.ServiceRequestError`
+        :raises ~azure.core.exceptions.ServiceRequestError: If the request fails.
         """
         _BearerTokenCredentialPolicyBase._enforce_https(request)  # pylint:disable=protected-access
 
diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_redirect.py b/sdk/core/azure-core/azure/core/pipeline/policies/_redirect.py
@@ -58,6 +58,7 @@
 
 def domain_changed(original_domain: Optional[str], url: str) -> bool:
     """Checks if the domain has changed.
+
     :param str original_domain: The original domain.
     :param str url: The new url.
     :rtype: bool
@@ -193,9 +194,9 @@ def send(self, request: PipelineRequest[HTTPRequestType]) -> PipelineResponse[HT
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest
-        :return: Returns the PipelineResponse or raises error if maximum redirects exceeded.
+        :return: The PipelineResponse.
         :rtype: ~azure.core.pipeline.PipelineResponse
-        :raises: ~azure.core.exceptions.TooManyRedirectsError if maximum redirects exceeded.
+        :raises ~azure.core.exceptions.TooManyRedirectsError: if maximum redirects exceeded.
         """
         retryable: bool = True
         redirect_settings = self.configure_redirects(request.context.options)
diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_redirect_async.py b/sdk/core/azure-core/azure/core/pipeline/policies/_redirect_async.py
@@ -65,9 +65,9 @@ async def send(
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest
-        :return: Returns the PipelineResponse or raises error if maximum redirects exceeded.
+        :return: the PipelineResponse.
         :rtype: ~azure.core.pipeline.PipelineResponse
-        :raises: ~azure.core.exceptions.TooManyRedirectsError if maximum redirects exceeded.
+        :raises ~azure.core.exceptions.TooManyRedirectsError: if maximum redirects exceeded.
         """
         redirects_remaining = True
         redirect_settings = self.configure_redirects(request.context.options)
diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_retry.py b/sdk/core/azure-core/azure/core/pipeline/policies/_retry.py
@@ -422,28 +422,21 @@ class RetryPolicy(RetryPolicyBase, HTTPPolicy[HTTPRequestType, HTTPResponseType]
 
     :keyword int retry_total: Total number of retries to allow. Takes precedence over other counts.
      Default value is 10.
-
     :keyword int retry_connect: How many connection-related errors to retry on.
      These are errors raised before the request is sent to the remote server,
      which we assume has not triggered the server to process the request. Default value is 3.
-
     :keyword int retry_read: How many times to retry on read errors.
      These errors are raised after the request was sent to the server, so the
      request may have side-effects. Default value is 3.
-
     :keyword int retry_status: How many times to retry on bad status codes. Default value is 3.
-
     :keyword float retry_backoff_factor: A backoff factor to apply between attempts after the second try
      (most errors are resolved immediately by a second try without a delay).
      In fixed mode, retry policy will always sleep for {backoff factor}.
      In 'exponential' mode, retry policy will sleep for: `{backoff factor} * (2 ** ({number of total retries} - 1))`
      seconds. If the backoff_factor is 0.1, then the retry will sleep
      for [0.0s, 0.2s, 0.4s, ...] between retries. The default value is 0.8.
-
     :keyword int retry_backoff_max: The maximum back off time. Default value is 120 seconds (2 minutes).
-
     :keyword RetryMode retry_mode: Fixed or exponential delay between attemps, default is exponential.
-
     :keyword int timeout: Timeout setting for the operation in seconds, default is 604800s (7 days).
 
     .. admonition:: Example:
@@ -522,10 +515,10 @@ def send(self, request: PipelineRequest[HTTPRequestType]) -> PipelineResponse[HT
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest
-        :return: Returns the PipelineResponse or raises error if maximum retries exceeded.
+        :return: The PipelineResponse.
         :rtype: ~azure.core.pipeline.PipelineResponse
-        :raises: ~azure.core.exceptions.AzureError if maximum retries exceeded.
-        :raises: ~azure.core.exceptions.ClientAuthenticationError if authentication
+        :raises ~azure.core.exceptions.AzureError: if maximum retries exceeded.
+        :raises ~azure.core.exceptions.ClientAuthenticationError: if authentication fails.
         """
         retry_active = True
         response = None
diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_retry_async.py b/sdk/core/azure-core/azure/core/pipeline/policies/_retry_async.py
@@ -57,23 +57,18 @@ class AsyncRetryPolicy(RetryPolicyBase, AsyncHTTPPolicy[HTTPRequestType, AsyncHT
 
     :keyword int retry_total: Total number of retries to allow. Takes precedence over other counts.
      Default value is 10.
-
     :keyword int retry_connect: How many connection-related errors to retry on.
      These are errors raised before the request is sent to the remote server,
      which we assume has not triggered the server to process the request. Default value is 3.
-
     :keyword int retry_read: How many times to retry on read errors.
      These errors are raised after the request was sent to the server, so the
      request may have side-effects. Default value is 3.
-
     :keyword int retry_status: How many times to retry on bad status codes. Default value is 3.
-
     :keyword float retry_backoff_factor: A backoff factor to apply between attempts after the second try
      (most errors are resolved immediately by a second try without a delay).
      Retry policy will sleep for: `{backoff factor} * (2 ** ({number of total retries} - 1))`
      seconds. If the backoff_factor is 0.1, then the retry will sleep
      for [0.0s, 0.2s, 0.4s, ...] between retries. The default value is 0.8.
-
     :keyword int retry_backoff_max: The maximum back off time. Default value is 120 seconds (2 minutes).
 
     .. admonition:: Example:
@@ -154,10 +149,10 @@ async def send(
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest
-        :return: Returns the PipelineResponse or raises error if maximum retries exceeded.
+        :return: The PipelineResponse.
         :rtype: ~azure.core.pipeline.PipelineResponse
-        :raise: ~azure.core.exceptions.AzureError if maximum retries exceeded.
-        :raise: ~azure.core.exceptions.ClientAuthenticationError if authentication fails
+        :raise ~azure.core.exceptions.AzureError: if maximum retries exceeded.
+        :raise ~azure.core.exceptions.ClientAuthenticationError: if authentication fails
         """
         retry_active = True
         response = None
diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_universal.py b/sdk/core/azure-core/azure/core/pipeline/policies/_universal.py
@@ -234,6 +234,7 @@ def user_agent(self) -> str:
 
     def add_user_agent(self, value: str) -> None:
         """Add value to current user agent with a space.
+
         :param str value: value to add to user agent.
         """
         self._user_agent = "{} {}".format(self._user_agent, value)
@@ -441,6 +442,7 @@ def on_request(  # pylint: disable=too-many-return-statements
         self, request: PipelineRequest[HTTPRequestType]
     ) -> None:
         """Logs HTTP method, url and headers.
+
         :param request: The PipelineRequest object.
         :type request: ~azure.core.pipeline.PipelineRequest
         """
diff --git a/sdk/core/azure-core/azure/core/pipeline/transport/_aiohttp.py b/sdk/core/azure-core/azure/core/pipeline/transport/_aiohttp.py
@@ -85,7 +85,6 @@ class AioHttpTransport(AsyncHttpTransport):
     :keyword session: The client session.
     :paramtype session: ~aiohttp.ClientSession
     :keyword bool session_owner: Session owner. Defaults True.
-
     :keyword bool use_env_settings: Uses proxy settings from environment. Defaults to True.
 
     .. admonition:: Example:
diff --git a/sdk/core/azure-core/azure/core/polling/base_polling.py b/sdk/core/azure-core/azure/core/polling/base_polling.py
@@ -113,15 +113,15 @@ def _succeeded(status):
 
 
 class BadStatus(Exception):
-    pass
+    """Exception raised when status is invalid."""
 
 
 class BadResponse(Exception):
-    pass
+    """Exception raised when response is invalid."""
 
 
 class OperationFailed(Exception):
-    pass
+    """Exception raised when operation failed or canceled."""
 
 
 def _as_json(response: AllHttpResponseType) -> Dict[str, Any]:
diff --git a/sdk/core/azure-core/azure/core/rest/_http_response_impl_async.py b/sdk/core/azure-core/azure/core/rest/_http_response_impl_async.py
@@ -46,6 +46,7 @@ def __getattr__(self, attr):
     def parts(self):
         """DEPRECATED: Assuming the content-type is multipart/mixed, will return the parts as an async iterator.
         This is deprecated and will be removed in a later release.
+
         :rtype: AsyncIterator
         :return: The parts of the response
         :raises ValueError: If the content is not multipart/mixed
@@ -95,6 +96,7 @@ async def read(self) -> bytes:
 
     async def iter_raw(self, **kwargs: Any) -> AsyncIterator[bytes]:
         """Asynchronously iterates over the response's bytes. Will not decompress in the process
+
         :return: An async iterator of bytes from the response
         :rtype: AsyncIterator[bytes]
         """
@@ -105,6 +107,7 @@ async def iter_raw(self, **kwargs: Any) -> AsyncIterator[bytes]:
 
     async def iter_bytes(self, **kwargs: Any) -> AsyncIterator[bytes]:
         """Asynchronously iterates over the response's bytes. Will decompress in the process
+
         :return: An async iterator of bytes from the response
         :rtype: AsyncIterator[bytes]
         """
diff --git a/sdk/core/azure-core/azure/core/rest/_rest_py3.py b/sdk/core/azure-core/azure/core/rest/_rest_py3.py
@@ -303,7 +303,7 @@ def json(self) -> Any:
 
         :return: The JSON deserialized response body
         :rtype: any
-        :raises json.decoder.JSONDecodeError or ValueError (in python 2.7) if object is not JSON decodable:
+        :raises json.decoder.JSONDecodeError: if the body is not valid JSON.
         """
 
     @abc.abstractmethod
@@ -312,7 +312,7 @@ def raise_for_status(self) -> None:
 
         If response is good, does nothing.
 
-        :raises ~azure.core.HttpResponseError if the object has an error status code.:
+        :raises ~azure.core.HttpResponseError: if the object has an error status code.
         """
 
 
diff --git a/sdk/core/azure-core/azure/core/settings.py b/sdk/core/azure-core/azure/core/settings.py
@@ -302,7 +302,7 @@ def __call__(self, value: Optional[ValidInputType] = None) -> ValueType:
         :type value: str or int or float or None
         :returns: the value of the setting
         :rtype: str or int or float
-        :raises: RuntimeError if no value can be determined
+        :raises RuntimeError: if no value can be determined
         """
 
         # 4. immediate values
diff --git a/sdk/core/azure-core/azure/core/tracing/_abstract_span.py b/sdk/core/azure-core/azure/core/tracing/_abstract_span.py
@@ -310,6 +310,7 @@ def set_http_attributes(
 class Link:
     """
     This is a wrapper class to link the context to the current tracer.
+
     :param headers: A dictionary of the request header as key value pairs.
     :type headers: dict
     :param attributes: Any additional attributes that should be added to link
diff --git a/sdk/core/azure-core/azure/core/utils/_connection_string_parser.py b/sdk/core/azure-core/azure/core/utils/_connection_string_parser.py
@@ -17,8 +17,7 @@ def parse_connection_string(conn_str: str, case_sensitive_keys: bool = False) ->
         default), all keys will be lower-cased. If set to `True`, the original casing of the keys will be preserved.
     :rtype: Mapping
     :returns: Dict of connection string key/value pairs.
-    :raises:
-        ValueError: if each key in conn_str does not have a corresponding value and
+    :raises ValueError: if each key in conn_str does not have a corresponding value and
             for other bad formatting of connection strings - including duplicate
             args, bad syntax, etc.
     """
diff --git a/sdk/core/azure-core/azure/core/utils/_messaging_shared.py b/sdk/core/azure-core/azure/core/utils/_messaging_shared.py
@@ -22,7 +22,7 @@ def _get_json_content(obj):
     :type obj: any
     :return: The JSON content of the object.
     :rtype: dict
-    :raises ValueError if JSON content cannot be loaded from the object
+    :raises ValueError: if JSON content cannot be loaded from the object.
     """
     msg = "Failed to load JSON content from the object."
     try:
diff --git a/sdk/core/azure-core/azure/core/utils/_pipeline_transport_rest_shared.py b/sdk/core/azure-core/azure/core/utils/_pipeline_transport_rest_shared.py
@@ -129,6 +129,7 @@ def _prepare_multipart_body_helper(http_request: "HTTPRequestType", content_inde
     correct context (sync/async)
 
     Does nothing if "set_multipart_mixed" was never called.
+
     :param http_request: The http request whose multipart body we are trying
      to prepare
     :type http_request: any
diff --git a/sdk/core/azure-core/azure/core/utils/_utils.py b/sdk/core/azure-core/azure/core/utils/_utils.py
@@ -170,7 +170,7 @@ def get_running_async_lock() -> AsyncContextManager:
 
     :return: An instance of the running async library's Lock class.
     :rtype: AsyncContextManager
-    :raises: RuntimeError if the current context is not running under an async library.
+    :raises RuntimeError: if the current context is not running under an async library.
     """
 
     try:
