Merge branch 'main' into add-logger-documentation

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.17.0](https://github.com/googleapis/gapic-generator-php/compare/v1.16.1...v1.17.0) (2024-10-30)
+
+
+### Features
+
+* Generic type for docs in async magic methods ([#732](https://github.com/googleapis/gapic-generator-php/issues/732)) ([68c88ed](https://github.com/googleapis/gapic-generator-php/commit/68c88eddcef45e100d357218e7f141d4f3b92a4d))
+
 ## [1.16.1](https://github.com/googleapis/gapic-generator-php/compare/v1.16.0...v1.16.1) (2024-08-08)
 
 

src/Generation/GapicClientV2Generator.php

@@ -236,7 +236,7 @@ private function magicAsyncDocs(): PhpDoc
             ->filter(fn($m) => !$m->isStreaming())
             ->map(fn($m) => PhpDoc::method(
                 $m->methodName . "Async",
-                $this->ctx->type(Type::fromName(PromiseInterface::class))->type->name,
+                $this->asyncReturnType($m),
                 $m->requestType->name, // the request type will already be imported for the sync variants
             ));
         return PhpDoc::block($methodDocs);
@@ -415,7 +415,7 @@ private function resourceMethods(): Vector
             return Vector::new();
         }
         $formattedName = AST::param(ResolvedType::string(), AST::var('formattedName'));
-        $template = AST::param(ResolvedType::string(), AST::var('template'), AST::NULL);
+        $template = AST::param(ResolvedType::string(true), AST::var('template'), AST::NULL);
 
         return $this->serviceDetails->resourceParts
             ->map(fn ($x) => $x->getFormatMethod()
@@ -887,4 +887,14 @@ private function snippetPathForMethod(MethodDetails $method): string
 
         return "samples/{$version}{$emptyClientName}/{$methodName}.php";
     }
+
+    private function asyncReturnType(MethodDetails $method): string
+    {
+        $returnType = $this->ctx->type(Type::fromName(PromiseInterface::class))->type->name;
+        $nestedType = ($method->hasEmptyResponse)
+            ? 'void'
+            : $this->ctx->type($method->methodReturnType)->type->name;
+
+        return sprintf('%s<%s>', $returnType, $nestedType);
+    }
 }

src/Utils/ResolvedType.php

@@ -18,6 +18,8 @@
 
 namespace Google\Generator\Utils;
 
+use Closure;
+
 /**
  * Represent a resolved type, ready to use in code output.
  * This class is required to allow a resolved type to be differentiated from other plain strings.
@@ -29,19 +31,19 @@ class ResolvedType
      *
      * @return ResolvedType
      */
-    public static function array(): ResolvedType
+    public static function array(bool $optional = false): ResolvedType
     {
-        return new ResolvedType(Type::array(), fn () => 'array');
+        return new ResolvedType(Type::array(), fn () => 'array', $optional);
     }
 
     /**
      * The 'string' built-in type.
      *
      * @return ResolvedType
      */
-    public static function string(): ResolvedType
+    public static function string(bool $optional = false): ResolvedType
     {
-        return new ResolvedType(Type::string(), fn () => 'string');
+        return new ResolvedType(Type::string(), fn () => 'string', $optional);
     }
 
     /**
@@ -69,19 +71,16 @@ public static function self(): ResolvedType
      *
      * @param string $typeName The resolved name of the type.
      */
-    public function __construct(Type $type, \Closure $fnToCode)
-    {
-        $this->type = $type;
-        $this->fnToCode = $fnToCode;
+    public function __construct(
+        /** @var Type *Readonly* The type of this resolved-type. */
+        public ReadOnly Type $type,
+        private Closure $fnToCode,
+        private bool $optional = false
+    ) {
     }
 
-    /** @var Type *Readonly* The type of this resolved-type. */
-    public Type $type;
-
-    private \Closure $fnToCode;
-
     public function toCode(): string
     {
-        return ($this->fnToCode)();
+        return ($this->optional ? '?' : '') . ($this->fnToCode)();
     }
 }

tests/Integration/goldens/functions/src/V1/Client/CloudFunctionsServiceClient.php

@@ -67,17 +67,17 @@
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
  *
- * @method PromiseInterface callFunctionAsync(CallFunctionRequest $request, array $optionalArgs = [])
- * @method PromiseInterface createFunctionAsync(CreateFunctionRequest $request, array $optionalArgs = [])
- * @method PromiseInterface deleteFunctionAsync(DeleteFunctionRequest $request, array $optionalArgs = [])
- * @method PromiseInterface generateDownloadUrlAsync(GenerateDownloadUrlRequest $request, array $optionalArgs = [])
- * @method PromiseInterface generateUploadUrlAsync(GenerateUploadUrlRequest $request, array $optionalArgs = [])
- * @method PromiseInterface getFunctionAsync(GetFunctionRequest $request, array $optionalArgs = [])
- * @method PromiseInterface getIamPolicyAsync(GetIamPolicyRequest $request, array $optionalArgs = [])
- * @method PromiseInterface listFunctionsAsync(ListFunctionsRequest $request, array $optionalArgs = [])
- * @method PromiseInterface setIamPolicyAsync(SetIamPolicyRequest $request, array $optionalArgs = [])
- * @method PromiseInterface testIamPermissionsAsync(TestIamPermissionsRequest $request, array $optionalArgs = [])
- * @method PromiseInterface updateFunctionAsync(UpdateFunctionRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<CallFunctionResponse> callFunctionAsync(CallFunctionRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> createFunctionAsync(CreateFunctionRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> deleteFunctionAsync(DeleteFunctionRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<GenerateDownloadUrlResponse> generateDownloadUrlAsync(GenerateDownloadUrlRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<GenerateUploadUrlResponse> generateUploadUrlAsync(GenerateUploadUrlRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<CloudFunction> getFunctionAsync(GetFunctionRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<Policy> getIamPolicyAsync(GetIamPolicyRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<PagedListResponse> listFunctionsAsync(ListFunctionsRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<Policy> setIamPolicyAsync(SetIamPolicyRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<TestIamPermissionsResponse> testIamPermissionsAsync(TestIamPermissionsRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> updateFunctionAsync(UpdateFunctionRequest $request, array $optionalArgs = [])
  */
 final class CloudFunctionsServiceClient
 {
@@ -268,14 +268,14 @@ public static function repositoryName(string $project, string $location, string
      * listed, then parseName will check each of the supported templates, and return
      * the first match.
      *
-     * @param string $formattedName The formatted name string
-     * @param string $template      Optional name of template to match
+     * @param string  $formattedName The formatted name string
+     * @param ?string $template      Optional name of template to match
      *
      * @return array An associative array from name component IDs to component values.
      *
      * @throws ValidationException If $formattedName could not be matched.
      */
-    public static function parseName(string $formattedName, string $template = null): array
+    public static function parseName(string $formattedName, ?string $template = null): array
     {
         return self::parseFormattedName($formattedName, $template);
     }

tests/Integration/goldens/redis/src/V1/Client/CloudRedisClient.php

@@ -80,19 +80,19 @@
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
  *
- * @method PromiseInterface createInstanceAsync(CreateInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface deleteInstanceAsync(DeleteInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface exportInstanceAsync(ExportInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface failoverInstanceAsync(FailoverInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface getInstanceAsync(GetInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface getInstanceAuthStringAsync(GetInstanceAuthStringRequest $request, array $optionalArgs = [])
- * @method PromiseInterface importInstanceAsync(ImportInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface listInstancesAsync(ListInstancesRequest $request, array $optionalArgs = [])
- * @method PromiseInterface rescheduleMaintenanceAsync(RescheduleMaintenanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface updateInstanceAsync(UpdateInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface upgradeInstanceAsync(UpgradeInstanceRequest $request, array $optionalArgs = [])
- * @method PromiseInterface getLocationAsync(GetLocationRequest $request, array $optionalArgs = [])
- * @method PromiseInterface listLocationsAsync(ListLocationsRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> createInstanceAsync(CreateInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> deleteInstanceAsync(DeleteInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> exportInstanceAsync(ExportInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> failoverInstanceAsync(FailoverInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<Instance> getInstanceAsync(GetInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<InstanceAuthString> getInstanceAuthStringAsync(GetInstanceAuthStringRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> importInstanceAsync(ImportInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<PagedListResponse> listInstancesAsync(ListInstancesRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> rescheduleMaintenanceAsync(RescheduleMaintenanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> updateInstanceAsync(UpdateInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<OperationResponse> upgradeInstanceAsync(UpgradeInstanceRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<Location> getLocationAsync(GetLocationRequest $request, array $optionalArgs = [])
+ * @method PromiseInterface<PagedListResponse> listLocationsAsync(ListLocationsRequest $request, array $optionalArgs = [])
  */
 final class CloudRedisClient
 {
@@ -245,14 +245,14 @@ public static function locationName(string $project, string $location): string
      * listed, then parseName will check each of the supported templates, and return
      * the first match.
      *
-     * @param string $formattedName The formatted name string
-     * @param string $template      Optional name of template to match
+     * @param string  $formattedName The formatted name string
+     * @param ?string $template      Optional name of template to match
      *
      * @return array An associative array from name component IDs to component values.
      *
      * @throws ValidationException If $formattedName could not be matched.
      */
-    public static function parseName(string $formattedName, string $template = null): array
+    public static function parseName(string $formattedName, ?string $template = null): array
     {
         return self::parseFormattedName($formattedName, $template);
     }