Deprecate C\first_async (aka C\gen_first)

Summary:
`C\first_async()` is made obsolete by await-as-an-expression in Hack.

Instead of:
  await C\first_async(some_async_function());

you should use:
  C\first(await some_async_function());

Reviewed By: fredemmott

Differential Revision: D25890718

fbshipit-source-id: 6dabf456fb4ee33f60294501dad80d4afc5605a1

src/c/async.php

@@ -14,22 +14,6 @@
  */
 namespace HH\Lib\C;
 
-/**
- * Returns the first element of the result of the given Awaitable, or null if
- * the Traversable is empty.
- *
- * For non-Awaitable Traversables, see `C\first`.
- *
- * Time complexity: O(1)
- * Space complexity: O(1)
- */
-async function first_async<T>(
-  Awaitable<Traversable<T>> $awaitable,
-): Awaitable<?T> {
-  $traversable = await $awaitable;
-  return first($traversable);
-}
-
 /**
  * Returns the first element of the result of the given Awaitable, or throws if
  * the Traversable is empty.

src/c/deprecated.php

@@ -0,0 +1,27 @@
+<?hh
+/*
+ *  Copyright (c) 2004-present, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the MIT license found in the
+ *  LICENSE file in the root directory of this source tree.
+ *
+ */
+
+namespace HH\Lib\C;
+
+/**
+ * Returns the first element of the result of the given Awaitable, or null if
+ * the Traversable is empty.
+ *
+ * For non-Awaitable Traversables, see `C\first`.
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+<<__Deprecated('use C\\first(await #A)')>>
+async function first_async<T>(
+  Awaitable<Traversable<T>> $awaitable,
+): Awaitable<?T> {
+  return first(await $awaitable);
+}

tests/c/CAsyncTest.php

@@ -16,42 +16,6 @@
 // @oss-disable: <<Oncalls('hack')>>
 final class CAsyncTest extends HackTest {
 
-  public static function provideTestGenFirst(
-  ): vec<(Awaitable<Traversable<mixed>>, mixed)> {
-    return vec[
-      tuple(
-        async {
-          return varray[];
-        },
-        null,
-      ),
-      tuple(
-        async {
-          return HackLibTestTraversables::getIterator(Vec\range(1, 5));
-        },
-        1,
-      ),
-      tuple(
-        async {
-          return dict[
-            '5' => '10',
-            '10' => '20',
-          ];
-        },
-        '10',
-      ),
-    ];
-  }
-
-  <<DataProvider('provideTestGenFirst')>>
-  public async function testFirstAsync<T>(
-    Awaitable<Traversable<T>> $awaitable,
-    ?T $expected,
-  ): Awaitable<void> {
-    $actual = await C\first_async($awaitable);
-    expect($actual)->toEqual($expected);
-  }
-
   public static function provideTestGenFirstx(
   ): vec<(Awaitable<Traversable<mixed>>, mixed)> {
     return vec[