Updates docstring for _make_request

Author: chalmerlowe

google/cloud/bigquery_v2/services/centralized_service/_helpers.py

@@ -3,7 +3,7 @@
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
+# You may obtain a copy of the License atp
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
@@ -14,9 +14,14 @@
 # limitations under the License.
 #
 
+from typing import Any, Callable, Optional, Type, TypeVar
+
+
+T = TypeVar("T")
+
 
 def _drop_self_key(kwargs):
-    "Drops 'self' key from a given kwargs dict."
+    """Drops 'self' key from a given kwargs dict."""
 
     if not isinstance(kwargs, dict):
         raise TypeError("kwargs must be a dict.")
@@ -25,13 +30,56 @@ def _drop_self_key(kwargs):
 
 
 def _make_request(
-    request_class,
-    user_request,
-    identifier_value,
+    request_class: Type[T],
+    user_request: Optional[T],
+    identifier_value: Optional[Any],
     identifier_name: str,
-    parser,
+    parser: Callable[..., Any],
     identifier_required: bool = True,
-):
+) -> T:
+    """A factory for creating *Request objects.
+
+    This function simplifies the creation of request objects by extracting identifier
+    values from strings (e.g., 'project_id.dataset_id') and using them to instantiate
+    the appropriate request object. It allows users to continue using identifier
+    strings with BigQueryClient methods, even though the underlying *ServiceClient
+    methods do not directly support this convenience.
+
+    For example, this helper is used in methods like:
+    - BigQueryClient.get_dataset()
+    - BigQueryClient.delete_dataset()
+
+    Args:
+        request_class: The class of the request object to create (e.g.,
+            GetDatasetRequest, ListModelsRequest).
+        user_request: A user-provided *Request object. If not None, this
+            object is returned directly.
+        identifier_value: The value to be parsed to create the request object
+            (e.g., a dataset_id for GetDatasetRequest).
+        identifier_name: The name of the identifier field (e.g., 'dataset_id',
+            'job_id').
+        parser: A callable that takes the identifier_value and returns a dict
+            of fields for the request object. For example, a parser could
+            separate a 'project_id.dataset_id' string into its components.
+        identifier_required: Whether the identifier is required. Defaults to True.
+
+    Returns:
+        A *Request object.
+
+    Raises:
+        ValueError: If both user_request and identifier_value are provided, or
+            if identifier_required is True and both are None.
+
+    Example:
+        request = _make_request(
+            request_class=dataset.GetDatasetRequest,
+            user_request=request,
+            identifier_value=dataset_id,
+            identifier_name="dataset_id",
+            parser=self._parse_dataset_id_to_dict,
+            identifier_required=True,
+        )
+    """
     if user_request is not None and identifier_value is not None:
         raise ValueError(
             f"Provide either a request object or '{identifier_name}', not both."