feat: add phpdoc examples tag (#636)

googleapis · Jun 6, 2023 · 500e006 · 500e006
1 parent 595b37b
commit 500e006
Show file tree

Hide file tree

Showing 8 changed files with 149 additions and 5 deletions.
diff --git a/src/Ast/PhpDoc.php b/src/Ast/PhpDoc.php
@@ -443,8 +443,31 @@ protected function toLines(Map $info): Vector
         };
     }
 
+    /**
+     * Add a code example to the PHP doc block via the @example tag.
+     *
+     * @param string $sampleFile The relative path to the generated sample file
+     *
+     * @return PhpDoc
+     */
+    public static function sample(string $sampleFile): PhpDoc
+    {
+        return new class($sampleFile) extends PhpDoc {
+            public function __construct($sampleFile)
+            {
+                $this->sampleFile = $sampleFile;
+                $this->isMethodDoc = true;
+            }
+            protected function toLines(Map $info = null): Vector
+            {
+                // @example samples/V1/ExampleClient/create_instance.php
+                return Vector::new(["@example {$this->sampleFile}", ""]);
+            }
+        };
+    }
+
     public static function method(string $name, string $response, string $request): PhpDoc
-    { 
+    {
         return new class($name, $response, $request) extends PhpDoc {
             public function __construct($name, $response, $request)
             {

diff --git a/src/CodeGenerator.php b/src/CodeGenerator.php
@@ -345,7 +345,7 @@ private static function generateServices(
             // [Start V2 GAPIC surface generation]
             if ($migrationMode != MigrationMode::PRE_MIGRATION_SURFACE_ONLY) {
                 $ctx = new SourceFileContext($service->gapicClientType->getNamespace(), $licenseYear);
-                $file = GapicClientV2Generator::generate($ctx, $service);
+                $file = GapicClientV2Generator::generate($ctx, $service, $generateSnippets);
                 $code = $file->toCode();
                 $code = Formatter::format($code);
                 yield ["src/{$version}Client/BaseClient/{$service->gapicClientV2Type->name}.php", $code];

diff --git a/src/Generation/GapicClientV2Generator.php b/src/Generation/GapicClientV2Generator.php
@@ -38,6 +38,8 @@
 use Google\Generator\Ast\PhpFile;
 use Google\Generator\Collections\Map;
 use Google\Generator\Collections\Vector;
+use Google\Generator\Utils\Helpers;
+use Google\Generator\Utils\MigrationMode;
 use Google\Generator\Utils\ResolvedType;
 use Google\Generator\Utils\Transport;
 use Google\Generator\Utils\Type;
@@ -47,18 +49,21 @@ class GapicClientV2Generator
 {
     private const CALL_OPTIONS_VAR = 'callOptions';
 
-    public static function generate(SourceFileContext $ctx, ServiceDetails $serviceDetails): PhpFile
+    public static function generate(SourceFileContext $ctx, ServiceDetails $serviceDetails, bool $generateSnippets): PhpFile
     {
-        return (new GapicClientV2Generator($ctx, $serviceDetails))->generateImpl();
+        return (new GapicClientV2Generator($ctx, $serviceDetails, $generateSnippets))->generateImpl();
     }
 
     private SourceFileContext $ctx;
     private ServiceDetails $serviceDetails;
+    // TODO(v2): This can be cleaned up after the v2 migration is complete.
+    private bool $generateSnippets;
 
-    private function __construct(SourceFileContext $ctx, ServiceDetails $serviceDetails)
+    private function __construct(SourceFileContext $ctx, ServiceDetails $serviceDetails, bool $generateSnippets)
     {
         $this->ctx = $ctx;
         $this->serviceDetails = $serviceDetails;
+        $this->generateSnippets = $generateSnippets;
     }
 
     private function generateImpl(): PhpFile
@@ -682,6 +687,12 @@ private function rpcMethod(MethodDetails $method): PhpClassMember
                                 AST::method($method->methodName . 'Async'))(),
                             '.')
                         : null,
+                    $this->generateSnippets && in_array(
+                        $this->serviceDetails->migrationMode,
+                        [MigrationMode::MIGRATING, MigrationMode::NEW_SURFACE_ONLY]
+                    )
+                        ? PhpDoc::sample($this->snippetPathForMethod($method))
+                        : null,
                     $usesRequest
                         ? PhpDoc::param($required, PhpDoc::text('A request to house fields associated with the call.'))
                         : null,
@@ -750,4 +761,16 @@ private function startCall($method, $callOptions, $request): AST
 
       return $call;
     }
+
+    private function snippetPathForMethod(MethodDetails $method): string
+    {
+        $methodName = Helpers::toSnakeCase($method->name);
+        $version = Helpers::nsVersionAndSuffixPath($this->serviceDetails->namespace);
+        if ($version !== '') {
+            $version .= '/';
+        }
+        $emptyClientName = $this->serviceDetails->emptyClientV2Type->name;
+
+        return "samples/{$version}{$emptyClientName}/{$methodName}.php";
+    }
 }
diff --git a/...ntegration/goldens/functions/src/V1/Client/BaseClient/CloudFunctionsServiceBaseClient.php b/...ntegration/goldens/functions/src/V1/Client/BaseClient/CloudFunctionsServiceBaseClient.php
@@ -297,6 +297,8 @@ public function __call($method, $args)
      *
      * The async variant is {@see self::callFunctionAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/call_function.php
+     *
      * @param CallFunctionRequest $request     A request to house fields associated with the call.
      * @param array               $callOptions {
      *     Optional.
@@ -323,6 +325,8 @@ public function callFunction(CallFunctionRequest $request, array $callOptions =
      *
      * The async variant is {@see self::createFunctionAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/create_function.php
+     *
      * @param CreateFunctionRequest $request     A request to house fields associated with the call.
      * @param array                 $callOptions {
      *     Optional.
@@ -349,6 +353,8 @@ public function createFunction(CreateFunctionRequest $request, array $callOption
      *
      * The async variant is {@see self::deleteFunctionAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/delete_function.php
+     *
      * @param DeleteFunctionRequest $request     A request to house fields associated with the call.
      * @param array                 $callOptions {
      *     Optional.
@@ -377,6 +383,8 @@ public function deleteFunction(DeleteFunctionRequest $request, array $callOption
      *
      * The async variant is {@see self::generateDownloadUrlAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/generate_download_url.php
+     *
      * @param GenerateDownloadUrlRequest $request     A request to house fields associated with the call.
      * @param array                      $callOptions {
      *     Optional.
@@ -425,6 +433,8 @@ public function generateDownloadUrl(GenerateDownloadUrlRequest $request, array $
      *
      * The async variant is {@see self::generateUploadUrlAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/generate_upload_url.php
+     *
      * @param GenerateUploadUrlRequest $request     A request to house fields associated with the call.
      * @param array                    $callOptions {
      *     Optional.
@@ -449,6 +459,8 @@ public function generateUploadUrl(GenerateUploadUrlRequest $request, array $call
      *
      * The async variant is {@see self::getFunctionAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/get_function.php
+     *
      * @param GetFunctionRequest $request     A request to house fields associated with the call.
      * @param array              $callOptions {
      *     Optional.
@@ -475,6 +487,8 @@ public function getFunction(GetFunctionRequest $request, array $callOptions = []
      *
      * The async variant is {@see self::getIamPolicyAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/get_iam_policy.php
+     *
      * @param GetIamPolicyRequest $request     A request to house fields associated with the call.
      * @param array               $callOptions {
      *     Optional.
@@ -499,6 +513,8 @@ public function getIamPolicy(GetIamPolicyRequest $request, array $callOptions =
      *
      * The async variant is {@see self::listFunctionsAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/list_functions.php
+     *
      * @param ListFunctionsRequest $request     A request to house fields associated with the call.
      * @param array                $callOptions {
      *     Optional.
@@ -524,6 +540,8 @@ public function listFunctions(ListFunctionsRequest $request, array $callOptions
      *
      * The async variant is {@see self::setIamPolicyAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/set_iam_policy.php
+     *
      * @param SetIamPolicyRequest $request     A request to house fields associated with the call.
      * @param array               $callOptions {
      *     Optional.
@@ -551,6 +569,8 @@ public function setIamPolicy(SetIamPolicyRequest $request, array $callOptions =
      *
      * The async variant is {@see self::testIamPermissionsAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/test_iam_permissions.php
+     *
      * @param TestIamPermissionsRequest $request     A request to house fields associated with the call.
      * @param array                     $callOptions {
      *     Optional.
@@ -575,6 +595,8 @@ public function testIamPermissions(TestIamPermissionsRequest $request, array $ca
      *
      * The async variant is {@see self::updateFunctionAsync()} .
      *
+     * @example samples/V1/CloudFunctionsServiceClient/update_function.php
+     *
      * @param UpdateFunctionRequest $request     A request to house fields associated with the call.
      * @param array                 $callOptions {
      *     Optional.