Some doc fixes (#38872)

* Some doc fixes

* Update sdk/search/azure-search-documents/azure/search/documents/_generated/_serialization.py

* Update sdk/search/azure-search-documents/azure/search/documents/_generated/_serialization.py

* Update sdk/search/azure-search-documents/azure/search/documents/_generated/_serialization.py

Author: xiangyan99

sdk/search/azure-search-documents/azure/search/documents/_generated/_serialization.py

@@ -456,7 +456,7 @@ def deserialize(cls: Type[ModelType], data: Any, content_type: Optional[str] = N
         :param str data: A str using RestAPI structure. JSON by default.
         :param str content_type: JSON by default, set application/xml if XML.
         :returns: An instance of this model
-        :raises: DeserializationError if something went wrong
+        :raises DeserializationError: if something went wrong
         :rtype: ModelType
         """
         deserializer = Deserializer(cls._infer_class_models())
@@ -479,7 +479,7 @@ def from_dict(
         :param function key_extractors: A key extractor function.
         :param str content_type: JSON by default, set application/xml if XML.
         :returns: An instance of this model
-        :raises: DeserializationError if something went wrong
+        :raises DeserializationError: if something went wrong
         :rtype: ModelType
         """
         deserializer = Deserializer(cls._infer_class_models())
@@ -626,7 +626,7 @@ def _serialize(  # pylint: disable=too-many-nested-blocks, too-many-branches, to
         :param object target_obj: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: str, dict
-        :raises: SerializationError if serialization fails.
+        :raises SerializationError: if serialization fails.
         :returns: The serialized data.
         """
         key_transformer = kwargs.get("key_transformer", self.key_transformer)
@@ -736,8 +736,8 @@ def body(self, data, data_type, **kwargs):
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: dict
-        :raises: SerializationError if serialization fails.
-        :raises: ValueError if data is None
+        :raises SerializationError: if serialization fails.
+        :raises ValueError: if data is None
         :returns: The serialized request body
         """
 
@@ -781,8 +781,8 @@ def url(self, name, data, data_type, **kwargs):
         :param str data_type: The type to be serialized from.
         :rtype: str
         :returns: The serialized URL path
-        :raises: TypeError if serialization fails.
-        :raises: ValueError if data is None
+        :raises TypeError: if serialization fails.
+        :raises ValueError: if data is None
         """
         try:
             output = self.serialize_data(data, data_type, **kwargs)
@@ -805,8 +805,8 @@ def query(self, name, data, data_type, **kwargs):
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: str, list
-        :raises: TypeError if serialization fails.
-        :raises: ValueError if data is None
+        :raises TypeError: if serialization fails.
+        :raises ValueError: if data is None
         :returns: The serialized query parameter
         """
         try:
@@ -835,8 +835,8 @@ def header(self, name, data, data_type, **kwargs):
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: str
-        :raises: TypeError if serialization fails.
-        :raises: ValueError if data is None
+        :raises TypeError: if serialization fails.
+        :raises ValueError: if data is None
         :returns: The serialized header
         """
         try:
@@ -855,9 +855,9 @@ def serialize_data(self, data, data_type, **kwargs):
 
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
-        :raises: AttributeError if required data is None.
-        :raises: ValueError if data is None
-        :raises: SerializationError if serialization fails.
+        :raises AttributeError: if required data is None.
+        :raises ValueError: if data is None
+        :raises SerializationError: if serialization fails.
         :returns: The serialized data.
         :rtype: str, int, float, bool, dict, list
         """
@@ -1192,7 +1192,7 @@ def serialize_rfc(attr, **kwargs):  # pylint: disable=unused-argument
 
         :param Datetime attr: Object to be serialized.
         :rtype: str
-        :raises: TypeError if format invalid.
+        :raises TypeError: if format invalid.
         :return: serialized rfc
         """
         try:
@@ -1218,7 +1218,7 @@ def serialize_iso(attr, **kwargs):  # pylint: disable=unused-argument
 
         :param Datetime attr: Object to be serialized.
         :rtype: str
-        :raises: SerializationError if format invalid.
+        :raises SerializationError: if format invalid.
         :return: serialized iso
         """
         if isinstance(attr, str):
@@ -1251,7 +1251,7 @@ def serialize_unix(attr, **kwargs):  # pylint: disable=unused-argument
 
         :param Datetime attr: Object to be serialized.
         :rtype: int
-        :raises: SerializationError if format invalid
+        :raises SerializationError: if format invalid
         :return: serialied unix
         """
         if isinstance(attr, int):
@@ -1488,7 +1488,7 @@ def __call__(self, target_obj, response_data, content_type=None):
         :param str target_obj: Target data type to deserialize to.
         :param requests.Response response_data: REST response object.
         :param str content_type: Swagger "produces" if available.
-        :raises: DeserializationError if deserialization fails.
+        :raises DeserializationError: if deserialization fails.
         :return: Deserialized object.
         :rtype: object
         """
@@ -1502,7 +1502,7 @@ def _deserialize(self, target_obj, data):  # pylint: disable=inconsistent-return
 
         :param str target_obj: Target data type to deserialize to.
         :param object data: Object to deserialize.
-        :raises: DeserializationError if deserialization fails.
+        :raises DeserializationError: if deserialization fails.
         :return: Deserialized object.
         :rtype: object
         """
@@ -1713,7 +1713,7 @@ def deserialize_data(self, data, data_type):  # pylint: disable=too-many-return-
 
         :param str data: The response string to be deserialized.
         :param str data_type: The type to deserialize to.
-        :raises: DeserializationError if deserialization fails.
+        :raises DeserializationError: if deserialization fails.
         :return: Deserialized object.
         :rtype: object
         """
@@ -1795,7 +1795,7 @@ def deserialize_object(self, attr, **kwargs):  # pylint: disable=too-many-return
         :param dict attr: Dictionary to be deserialized.
         :return: Deserialized object.
         :rtype: dict
-        :raises: TypeError if non-builtin datatype encountered.
+        :raises TypeError: if non-builtin datatype encountered.
         """
         if attr is None:
             return None
@@ -1841,7 +1841,7 @@ def deserialize_basic(self, attr, data_type):  # pylint: disable=too-many-return
         :param str data_type: deserialization data type.
         :return: Deserialized basic type.
         :rtype: str, int, float or bool
-        :raises: TypeError if string format is not valid.
+        :raises TypeError: if string format is not valid.
         """
         # If we're here, data is supposed to be a basic type.
         # If it's still an XML node, take the text
@@ -1932,7 +1932,7 @@ def deserialize_bytearray(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized bytearray
         :rtype: bytearray
-        :raises: TypeError if string format invalid.
+        :raises TypeError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1945,7 +1945,7 @@ def deserialize_base64(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized base64 string
         :rtype: bytearray
-        :raises: TypeError if string format invalid.
+        :raises TypeError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1960,7 +1960,7 @@ def deserialize_decimal(attr):
 
         :param str attr: response string to be deserialized.
         :return: Deserialized decimal
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         :rtype: decimal
         """
         if isinstance(attr, ET.Element):
@@ -1978,7 +1978,7 @@ def deserialize_long(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized int
         :rtype: long or int
-        :raises: ValueError if string format invalid.
+        :raises ValueError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1991,7 +1991,7 @@ def deserialize_duration(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized duration
         :rtype: TimeDelta
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -2009,7 +2009,7 @@ def deserialize_date(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized date
         :rtype: Date
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -2025,7 +2025,7 @@ def deserialize_time(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized time
         :rtype: datetime.time
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -2040,7 +2040,7 @@ def deserialize_rfc(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized RFC datetime
         :rtype: Datetime
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -2063,7 +2063,7 @@ def deserialize_iso(attr):
         :param str attr: response string to be deserialized.
         :return: Deserialized ISO datetime
         :rtype: Datetime
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -2101,7 +2101,7 @@ def deserialize_unix(attr):
         :param int attr: Object to be serialized.
         :return: Deserialized datetime
         :rtype: Datetime
-        :raises: DeserializationError if format invalid
+        :raises DeserializationError: if format invalid
         """
         if isinstance(attr, ET.Element):
             attr = int(attr.text)  # type: ignore

sdk/search/azure-search-documents/azure/search/documents/_paging.py

@@ -43,6 +43,7 @@ def unpack_continuation_token(token):
 
 
 class SearchItemPaged(ItemPaged[ReturnType]):
+    """A pageable list of search results."""
     def __init__(self, *args, **kwargs) -> None:
         super(SearchItemPaged, self).__init__(*args, **kwargs)
         self._first_page_iterator_instance: Optional[SearchPageIterator] = None
@@ -116,6 +117,7 @@ def wrapper(self, *args, **kw):
 
 
 class SearchPageIterator(PageIterator):
+    """An iterator over search results."""
     def __init__(self, client, initial_query, kwargs, continuation_token=None) -> None:
         super(SearchPageIterator, self).__init__(
             get_next=self._get_next_cb,

sdk/search/azure-search-documents/azure/search/documents/_queries.py

@@ -58,10 +58,8 @@ def order_by(self, *fields: Union[str, List[str]]) -> None:
 
         :param fields: A list of fields for the query result to be ordered by.
         :type fields: str or list[str]
-        :raises: ValueError
+        :raises ValueError: If no fields are provided.
         """
-        if not fields:
-            raise ValueError("At least one field must be provided")
         if not fields:
             raise ValueError("At least one field must be provided")
         selects = []
@@ -78,7 +76,7 @@ def select(self, *fields: Union[str, List[str]]) -> None:
 
         :param fields: A list of fields for the query result to return.
         :type fields: str or list[str]
-        :raises: ValueError
+        :raises ValueError: If no fields are provided.
         """
         if not fields:
             raise ValueError("At least one field must be provided")
@@ -104,10 +102,8 @@ def order_by(self, *fields: Union[str, List[str]]) -> None:
 
         :param fields: A list of fields for the query result to be ordered by.
         :type fields: str or list[str]
-        :raises: ValueError
+        :raises ValueError: If no fields are provided.
         """
-        if not fields:
-            raise ValueError("At least one field must be provided")
         if not fields:
             raise ValueError("At least one field must be provided")
         selects = []
@@ -124,7 +120,7 @@ def select(self, *fields: Union[str, List[str]]) -> None:
 
         :param fields: A list of fields for the query result to return.
         :type fields: str or list[str]
-        :raises: ValueError
+        :raises ValueError: If no fields are provided.
         """
         if not fields:
             raise ValueError("At least one field must be provided")

sdk/search/azure-search-documents/azure/search/documents/_search_client.py

@@ -101,6 +101,7 @@ def __repr__(self) -> str:
 
     def close(self) -> None:
         """Close the session.
+        
         :return: None
         :rtype: None
         """

sdk/search/azure-search-documents/azure/search/documents/_search_indexing_buffered_sender.py

@@ -111,6 +111,7 @@ def actions(self) -> List[IndexAction]:
     @distributed_trace
     def close(self, **kwargs) -> None:  # pylint: disable=unused-argument
         """Close the session.
+        
         :return: None
         :rtype: None
         """

sdk/search/azure-search-documents/azure/search/documents/aio/_paging.py

@@ -17,6 +17,7 @@
 
 
 class AsyncSearchItemPaged(AsyncItemPaged[ReturnType]):
+    """A pageable list of search results."""
     def __init__(self, *args, **kwargs) -> None:
         super(AsyncSearchItemPaged, self).__init__(*args, **kwargs)
         self._first_page_iterator_instance: Optional[AsyncSearchPageIterator] = None
@@ -99,6 +100,7 @@ async def wrapper(self, *args, **kw):
 
 
 class AsyncSearchPageIterator(AsyncPageIterator[ReturnType]):
+    """An iterator of search results."""
     def __init__(self, client, initial_query, kwargs, continuation_token=None) -> None:
         super(AsyncSearchPageIterator, self).__init__(
             get_next=self._get_next_cb,

sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py

@@ -103,6 +103,7 @@ def __repr__(self) -> str:
 
     async def close(self) -> None:
         """Close the session.
+        
         :return: None
         :rtype: None
         """