From a85e0583bd562d2cfb86ce7f46a2f05ea1ac2154 Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <wilfred@fb.com>
Date: Tue, 22 Feb 2022 12:44:46 -0800
Subject: [PATCH] Show Vector/Map/Set doc comments when hovering over literals

Summary: Previously we would should hover information on type hints, but not on literals. Add hover information for literals too.

Differential Revision: D33826160

fbshipit-source-id: 3105627f8bc7b19e51a60af831f2940971f12003
---
 hphp/hack/src/server/identifySymbolService.ml |  6 +++++
 hphp/hack/test/hover/immmap_literal.php       |  6 +++++
 hphp/hack/test/hover/immmap_literal.php.exp   | 24 +++++++++++++++++++
 hphp/hack/test/hover/map_literal.php          |  6 +++++
 hphp/hack/test/hover/map_literal.php.exp      | 33 +++++++++++++++++++++++++++
 hphp/hack/test/hover/vector_literal.php       |  6 +++++
 hphp/hack/test/hover/vector_literal.php.exp   | 24 +++++++++++++++++++
 7 files changed, 105 insertions(+)
 create mode 100644 hphp/hack/test/hover/immmap_literal.php
 create mode 100644 hphp/hack/test/hover/immmap_literal.php.exp
 create mode 100644 hphp/hack/test/hover/map_literal.php
 create mode 100644 hphp/hack/test/hover/map_literal.php.exp
 create mode 100644 hphp/hack/test/hover/vector_literal.php
 create mode 100644 hphp/hack/test/hover/vector_literal.php.exp

diff --git a/hphp/hack/src/server/identifySymbolService.ml b/hphp/hack/src/server/identifySymbolService.ml
index 0454322d25c..c62e866cfd4 100644
--- a/hphp/hack/src/server/identifySymbolService.ml
+++ b/hphp/hack/src/server/identifySymbolService.ml
@@ -253,6 +253,12 @@ let visitor =
               (remove_apostrophes_from_function_eval mid)
               ~is_method:true
               ~is_const:false
+        | Aast.ValCollection (kind, _, _) ->
+          let type_name = Aast.show_vc_kind kind in
+          process_class_id (pos, "\\HH\\" ^ type_name)
+        | Aast.KeyValCollection (kind, _, _) ->
+          let type_name = Aast.show_kvc_kind kind in
+          process_class_id (pos, "\\HH\\" ^ type_name)
         | Aast.EnumClassLabel (enum_name, label_name) ->
           begin
             match enum_name with
diff --git a/hphp/hack/test/hover/immmap_literal.php b/hphp/hack/test/hover/immmap_literal.php
new file mode 100644
index 00000000000..e24b5fd39fb
--- /dev/null
+++ b/hphp/hack/test/hover/immmap_literal.php
@@ -0,0 +1,6 @@
+<?hh
+
+function foo(): void {
+  $x = ImmMap {};
+  //   ^ hover-at-caret
+}
diff --git a/hphp/hack/test/hover/immmap_literal.php.exp b/hphp/hack/test/hover/immmap_literal.php.exp
new file mode 100644
index 00000000000..c54e58219f0
--- /dev/null
+++ b/hphp/hack/test/hover/immmap_literal.php.exp
@@ -0,0 +1,24 @@
+final class ImmMap
+`ImmMap` is an immutable `Map`. HHVM provides a native implementation for
+this class. The PHP class definition below is not actually used at run time;
+it is simply provided for the typechecker and for developer reference.
+
+A `ImmMap` cannot be mutated. No elements can be added or removed from it,
+nor can elements be overwritten using assignment (i.e. `$c[$k] = $v` is
+not allowed).
+
+Construct it with a `Traversable`:
+
+```
+$a = dict['a' => 1, 'b' => 2];
+$fm = new ImmMap($a);
+```
+
+or use the literal syntax
+
+```
+$fm = ImmMap {'a' => 1, 'b' => 2};
+```
+
+@guide /hack/collections/introduction
+@guide /hack/collections/classes
diff --git a/hphp/hack/test/hover/map_literal.php b/hphp/hack/test/hover/map_literal.php
new file mode 100644
index 00000000000..565bde1e5fd
--- /dev/null
+++ b/hphp/hack/test/hover/map_literal.php
@@ -0,0 +1,6 @@
+<?hh
+
+function foo(): void {
+  $x = Map {};
+  //   ^ hover-at-caret
+}
diff --git a/hphp/hack/test/hover/map_literal.php.exp b/hphp/hack/test/hover/map_literal.php.exp
new file mode 100644
index 00000000000..b15d7f1c763
--- /dev/null
+++ b/hphp/hack/test/hover/map_literal.php.exp
@@ -0,0 +1,33 @@
+final class Map
+`Map` is an ordered dictionary-style collection. HHVM provides a native
+implementation for this class. The PHP class definition below is not
+actually used at run time; it is simply provided for the typechecker and for
+developer reference.
+
+Like all objects in PHP, `Map`s have reference-like semantics. When a caller
+passes a `Map` to a callee, the callee can modify the `Map` and the caller
+will see the changes. `Map`s do not have "copy-on-write" semantics.
+
+`Map`s preserve insertion order of key/value pairs. When iterating over a
+`Map`, the key/value pairs appear in the order they were inserted. Also,
+`Map`s do not automagically convert integer-like `string` keys (ex. `"123"`)
+into integer keys.
+
+`Map`s only support `int` keys and `string` keys. If a key of a different
+type is used, an exception will be thrown.
+
+`Map`s support `$m[$k]` style syntax for getting and setting values by key.
+`Map`s also support `isset($m[$k])` and `empty($m[$k])` syntax, and they
+provide similar semantics as arrays. Adding an element with square bracket
+syntax `[]` is supported either by providing a key between the brackets or
+a `Pair` on the right-hand side. e.g.,
+`$m[$k] = $v` is supported
+`$m[] = Pair {$k, $v}` is supported
+`$m[] = $v` is not supported.
+
+`Map`s do not support iterating while new keys are being added or elements
+are being removed. When a new key is added or an element is removed, all
+iterators that point to the `Map` shall be considered invalid.
+
+@guide /hack/collections/introduction
+@guide /hack/collections/classes
diff --git a/hphp/hack/test/hover/vector_literal.php b/hphp/hack/test/hover/vector_literal.php
new file mode 100644
index 00000000000..721332e59c7
--- /dev/null
+++ b/hphp/hack/test/hover/vector_literal.php
@@ -0,0 +1,6 @@
+<?hh
+
+function foo(): void {
+  $x = Vector {};
+  //   ^ hover-at-caret
+}
diff --git a/hphp/hack/test/hover/vector_literal.php.exp b/hphp/hack/test/hover/vector_literal.php.exp
new file mode 100644
index 00000000000..6ce0463eaf8
--- /dev/null
+++ b/hphp/hack/test/hover/vector_literal.php.exp
@@ -0,0 +1,24 @@
+final class Vector
+`Vector` is a stack-like collection. HHVM provides a native implementation
+for this class. The PHP class definition below is not actually used at run
+time; it is simply provided for the typechecker and for developer reference.
+
+Like all objects in PHP, `Vector`s have reference-like semantics. When a
+caller passes a `Vector` to a callee, the callee can modify the `Vector` and
+the caller will see the changes. `Vector`s do not have "copy-on-write"
+semantics.
+
+`Vector`s only support integer keys. If a non-integer key is used, an
+exception will be thrown.
+
+`Vector`s support `$m[$k]` style syntax for getting and setting values by
+key. `Vector`s also support `isset($m[$k])` and `empty($m[$k])` syntax, and
+they provide similar semantics as arrays. Elements can be added to a
+`Vector` using `$m[] = ..` syntax.
+
+`Vector`s do not support iterating while new elements are being added or
+elements are being removed. When a new element is added or removed, all
+iterators that point to the `Vector` shall be considered invalid.
+
+@guide /hack/collections/introduction
+@guide /hack/collections/classes
-- 
2.11.4.GIT