Fix some doc issues in core (Azure#41322)

* Fix some doc issues in core

* updates

* updates

* update

* updates

Author: xiangyan99

sdk/core/azure-core/azure/core/credentials.py

@@ -116,7 +116,11 @@ def get_token_info(self, *scopes: str, options: Optional[TokenRequestOptions] =
         ...
 
     def close(self) -> None:
-        pass
+        """Close the credential, releasing any resources it holds.
+
+        :return: None
+        :rtype: None
+        """
 
 
 TokenProvider = Union[TokenCredential, SupportsTokenInfo]
@@ -171,7 +175,7 @@ def update(self, key: str) -> None:
         to update long-lived clients.
 
         :param str key: The key used to authenticate to an Azure service
-        :raises: ValueError or TypeError
+        :raises ValueError or TypeError: If the key is None, empty, or not a string.
         """
         if not key:
             raise ValueError("The key used for updating can not be None or empty")

sdk/core/azure-core/azure/core/credentials_async.py

@@ -39,7 +39,11 @@ async def get_token(
         ...
 
     async def close(self) -> None:
-        pass
+        """Close the credential, releasing any resources.
+
+        :return: None
+        :rtype: None
+        """
 
     async def __aexit__(
         self,
@@ -70,7 +74,11 @@ async def get_token_info(self, *scopes: str, options: Optional[TokenRequestOptio
         ...
 
     async def close(self) -> None:
-        pass
+        """Close the credential, releasing any resources.
+
+        :return: None
+        :rtype: None
+        """
 
     async def __aexit__(
         self,

sdk/core/azure-core/azure/core/paging.py

@@ -69,6 +69,13 @@ def __iter__(self) -> Iterator[Iterator[ReturnType]]:
         return self
 
     def __next__(self) -> Iterator[ReturnType]:
+        """Get the next page in the iterator.
+
+        :returns: An iterator of objects in the next page.
+        :rtype: iterator[ReturnType]
+        :raises StopIteration: If there are no more pages to return.
+        :raises AzureError: If the request fails.
+        """
         if self.continuation_token is None and self._did_a_call_already:
             raise StopIteration("End of paging")
         try:
@@ -118,6 +125,12 @@ def __iter__(self) -> Iterator[ReturnType]:
         return self
 
     def __next__(self) -> ReturnType:
+        """Get the next item in the iterator.
+
+        :returns: The next item in the iterator.
+        :rtype: ReturnType
+        :raises StopIteration: If there are no more items to return.
+        """
         if self._page_iterator is None:
             self._page_iterator = itertools.chain.from_iterable(self.by_page())
         return next(self._page_iterator)

sdk/core/azure-core/azure/core/pipeline/__init__.py

@@ -107,18 +107,18 @@ def __delitem__(self, key: str) -> None:
     def clear(  # pylint: disable=docstring-missing-return, docstring-missing-rtype
         self,
     ) -> None:
-        """Context objects cannot be cleared.
+        """Clears the context objects.
 
-        :raises: TypeError
+        :raises TypeError: If context objects cannot be cleared
         """
         raise TypeError("Context objects cannot be cleared.")
 
     def update(  # pylint: disable=docstring-missing-return, docstring-missing-rtype, docstring-missing-param
         self, *args: Any, **kwargs: Any
     ) -> None:
-        """Context objects cannot be updated.
+        """Updates the context objects.
 
-        :raises: TypeError
+        :raises TypeError: If context objects cannot be updated
         """
         raise TypeError("Context objects cannot be updated.")
 
@@ -135,7 +135,7 @@ def pop(self, *args: Any) -> Any:
         :type args: str
         :return: The value for this key.
         :rtype: any
-        :raises: ValueError If the key is in the protected list.
+        :raises ValueError: If the key is in the protected list.
         """
         if args and args[0] in self._protected:
             raise ValueError("Context value {} cannot be popped.".format(args[0]))

sdk/core/azure-core/azure/core/pipeline/policies/_authentication.py

@@ -268,6 +268,11 @@ def __init__(  # pylint: disable=unused-argument
         self._prefix = prefix + " " if prefix else ""
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
+        """Called before the policy sends a request.
+
+        :param request: The request to be modified before sending.
+        :type request: ~azure.core.pipeline.PipelineRequest
+        """
         request.http_request.headers[self._name] = f"{self._prefix}{self._credential.key}"
 
 
@@ -290,6 +295,11 @@ def __init__(
         self._credential = credential
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
+        """Called before the policy sends a request.
+
+        :param request: The request to be modified before sending.
+        :type request: ~azure.core.pipeline.PipelineRequest
+        """
         url = request.http_request.url
         query = request.http_request.query
         signature = self._credential.signature

sdk/core/azure-core/azure/core/pipeline/policies/_distributed_tracing.py

@@ -101,6 +101,11 @@ def __init__(self, *, instrumentation_config: Optional[Mapping[str, Any]] = None
         self._instrumentation_config = instrumentation_config
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
+        """Starts a span for the network call.
+
+        :param request: The PipelineRequest object
+        :type request: ~azure.core.pipeline.PipelineRequest
+        """
         ctxt = request.context.options
         try:
             tracing_options: TracingOptions = ctxt.pop("tracing_options", {})
@@ -161,8 +166,8 @@ def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
                 token = tracer._suppress_auto_http_instrumentation()  # pylint: disable=protected-access
                 request.context[self._SUPPRESSION_TOKEN] = token
 
-        except Exception as err:  # pylint: disable=broad-except
-            _LOGGER.warning("Unable to start network span: %s", err)
+        except Exception:  # pylint: disable=broad-except
+            _LOGGER.warning("Unable to start network span.")
 
     def end_span(
         self,
@@ -234,9 +239,21 @@ def on_response(
         request: PipelineRequest[HTTPRequestType],
         response: PipelineResponse[HTTPRequestType, HTTPResponseType],
     ) -> None:
+        """Ends the span for the network call and updates its status.
+
+        :param request: The PipelineRequest object
+        :type request: ~azure.core.pipeline.PipelineRequest
+        :param response: The PipelineResponse object
+        :type response: ~azure.core.pipeline.PipelineResponse
+        """
         self.end_span(request, response=response.http_response)
 
     def on_exception(self, request: PipelineRequest[HTTPRequestType]) -> None:
+        """Ends the span for the network call and updates its status with exception info.
+
+        :param request: The PipelineRequest object
+        :type request: ~azure.core.pipeline.PipelineRequest
+        """
         self.end_span(request, exc_info=sys.exc_info())
 
     def _set_http_client_span_attributes(

sdk/core/azure-core/azure/core/pipeline/policies/_retry.py

@@ -66,6 +66,7 @@
 
 class RetryMode(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     # pylint: disable=enum-must-be-uppercase
+    """Enum for retry modes."""
     Exponential = "exponential"
     Fixed = "fixed"
 

sdk/core/azure-core/azure/core/pipeline/policies/_universal.py

@@ -510,14 +510,21 @@ def on_request(  # pylint: disable=too-many-return-statements
             log_string += "\nNo body was attached to the request"
             logger.info(log_string)
 
-        except Exception as err:  # pylint: disable=broad-except
-            logger.warning("Failed to log request: %s", repr(err))
+        except Exception:  # pylint: disable=broad-except
+            logger.warning("Failed to log request.")
 
     def on_response(
         self,
         request: PipelineRequest[HTTPRequestType],
         response: PipelineResponse[HTTPRequestType, HTTPResponseType],
     ) -> None:
+        """Logs HTTP response status and headers.
+
+        :param request: The PipelineRequest object.
+        :type request: ~azure.core.pipeline.PipelineRequest
+        :param response: The PipelineResponse object.
+        :type response: ~azure.core.pipeline.PipelineResponse
+        """
         http_response = response.http_response
 
         # Get logger in my context first (request has been retried)
@@ -545,8 +552,8 @@ def on_response(
                 value = self._redact_header(res_header, value)
                 log_string += "\n    '{}': '{}'".format(res_header, value)
             logger.info(log_string)
-        except Exception as err:  # pylint: disable=broad-except
-            logger.warning("Failed to log response: %s", repr(err))
+        except Exception:  # pylint: disable=broad-except
+            logger.warning("Failed to log response.")
 
 
 class ContentDecodePolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseType]):
@@ -683,6 +690,11 @@ def deserialize_from_http_generics(
         return cls.deserialize_from_text(response.text(encoding), mime_type, response=response)
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
+        """Set the response encoding in the request context.
+
+        :param request: The PipelineRequest object.
+        :type request: ~azure.core.pipeline.PipelineRequest
+        """
         options = request.context.options
         response_encoding = options.pop("response_encoding", self._response_encoding)
         if response_encoding:
@@ -743,6 +755,11 @@ def __init__(
         self.proxies = proxies
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
+        """Adds the proxy information to the request context.
+
+        :param request: The PipelineRequest object
+        :type request: ~azure.core.pipeline.PipelineRequest
+        """
         ctxt = request.context.options
         if self.proxies and "proxies" not in ctxt:
             ctxt["proxies"] = self.proxies

sdk/core/azure-core/azure/core/pipeline/transport/_aiohttp.py

@@ -141,6 +141,7 @@ async def __aexit__(
         await self.close()
 
     async def open(self):
+        """Opens the connection."""
         if self._has_been_opened and not self.session:
             raise ValueError(
                 "HTTP transport has already been closed. "
@@ -438,7 +439,7 @@ async def __anext__(self):
         except aiohttp.client_exceptions.ClientPayloadError as err:
             # This is the case that server closes connection before we finish the reading. aiohttp library
             # raises ClientPayloadError.
-            _LOGGER.warning("Incomplete download: %s", err)
+            _LOGGER.warning("Incomplete download.")
             internal_response.close()
             raise IncompleteReadError(err, error=err) from err
         except aiohttp.client_exceptions.ClientResponseError as err:
@@ -448,7 +449,7 @@ async def __anext__(self):
         except aiohttp.client_exceptions.ClientError as err:
             raise ServiceRequestError(err, error=err) from err
         except Exception as err:
-            _LOGGER.warning("Unable to stream download: %s", err)
+            _LOGGER.warning("Unable to stream download.")
             internal_response.close()
             raise
 

sdk/core/azure-core/azure/core/pipeline/transport/_base.py

@@ -507,6 +507,8 @@ def __repr__(self) -> str:
 
 
 class HttpResponse(_HttpResponseBase):
+    """Represent a HTTP response."""
+
     def stream_download(self, pipeline: Pipeline[HttpRequest, "HttpResponse"], **kwargs: Any) -> Iterator[bytes]:
         """Generator for streaming request body data.