Update annotation toolchain to support Async methods

build/ClassAnnotationUpdater.php

@@ -30,6 +30,12 @@ public function __construct(
         $this->removeMatching = $removeMatching;
     }
 
+    /**
+     * Performs update on class file and lints the output. If the output fails
+     * linting, the change is reverted.
+     *
+     * @return bool TRUE on success, FALSE on failure
+     */
     public function update()
     {
         // copy the code into memory

build/ClientAnnotator.php

@@ -19,36 +19,49 @@ public function __construct($clientClassName)
         $this->reflection = new ReflectionClass($clientClassName);
     }
 
+    /**
+     * Adds @method annotations to a client class.
+     *
+     * @return bool TRUE on success, FALSE on failure
+     */
     public function updateApiMethodAnnotations()
     {
-        return (new ClassAnnotationUpdater(
+        $updater = new ClassAnnotationUpdater(
             $this->reflection,
             $this->getMethodAnnotations(),
             $this->getDefaultDocComment(),
             '/^\* @method \\\\Aws\\\\Result /'
-        ))
-            ->update();
+        );
+
+        return $updater->update();
     }
 
     private function getMethodAnnotations()
     {
         $annotations = [];
 
-        foreach ($this->getMethods() as $method => $apiVersions) {
-            $signature = lcfirst($method) . '(array $args = [])';
-            $annotation = " * @method \\Aws\\Result $signature";
-
-            if ($apiVersions !== $this->getVersions()) {
-                $supportedIn = implode(', ', $apiVersions);
-                $annotation .= " (supported in versions $supportedIn)";
+        foreach ($this->getMethods() as $command => $apiVersions) {
+            foreach ([$command, "{$command}Async"] as $method) {
+                $annotations []= $this->getAnnotationLine($method, $apiVersions);
             }
-
-            $annotations []= $annotation;
         }
 
         return $annotations;
     }
 
+    private function getAnnotationLine($method, array $versionsWithSupport)
+    {
+        $signature = lcfirst($method) . '(array $args = [])';
+        $annotation = " * @method \\Aws\\Result $signature";
+
+        if ($versionsWithSupport !== $this->getVersions()) {
+            $supportedIn = implode(', ', $versionsWithSupport);
+            $annotation .= " (supported in versions $supportedIn)";
+        }
+
+        return $annotation;
+    }
+
     private function getMethods()
     {
         if (empty($this->methods)) {

build/annotate-client-locator.php

@@ -19,10 +19,10 @@
     . ' \\\\Aws\\\\(?:[a-zA-Z0-9]+)\\\\(?:[a-zA-Z0-9]+)Client'
     . ' create(?:[a-zA-Z0-9]+)\\(array \$args = \\[\\]\\)/';
 
-(new ClassAnnotationUpdater(
+$updater = new ClassAnnotationUpdater(
     new ReflectionClass(\Aws\Sdk::class),
     $annotations,
     '',
     $previousAnnotationPattern
-))
-    ->update();
+);
+$updater->update();

build/annotate-clients.php

@@ -55,10 +55,12 @@
 
 foreach (array_unique($options['class']) as $classToUpdate) {
     // Update the @method annotations on a client.
-    (new ClientAnnotator($classToUpdate))
-        ->updateApiMethodAnnotations()
-        || trigger_error(
+    $annotator = new ClientAnnotator($classToUpdate);
+
+    if (!$annotator->updateApiMethodAnnotations()) {
+        trigger_error(
             "Unable to update annotations on $classToUpdate",
             E_USER_WARNING
         );
+    }
 }

build/docs/theme/class.latte

@@ -275,7 +275,14 @@
         </div>
         {/if}
 
-        {if $ownMagicMethods && (!$class->parentClass || $class->parentClass->name !== 'Aws\AwsClient')}
+        {var $isAwsClient = false}
+        {foreach $class->parentClasses as $parent}
+            {if $parent->name === 'Aws\AwsClient'}
+                {var $isAwsClient = true}
+            {/if}
+        {/foreach}
+
+        {if $ownMagicMethods && !$isAwsClient}
         <h3>Magic methods summary</h3>
         <div class="element-list" id="magicMethods" n:if="$ownMagicMethods">
             {foreach $ownMagicMethods as $method}