[flow] Refine the custom error message

Summary:
This diff refines the custom error explanation a little bit. It will have the format of

```
Description of `T`: <desc>. Example for `T`: `<code>`.
```

Changelog: [internal]

Reviewed By: panagosg7

Differential Revision: D86468338

fbshipit-source-id: a425065230a6d754f80b37e28cc7c8a80fb5debc

Author: SamChou19815

src/typing/errors/error_message.ml

@@ -969,8 +969,8 @@ let map_loc_of_explanation (f : 'a -> 'b) =
       { name; declaration = f declaration; providers = Base.List.map ~f providers }
   | ExplanationConcreteEnumCasting { representation_type; casting_syntax } ->
     ExplanationConcreteEnumCasting { representation_type; casting_syntax }
-  | ExplanationCustomError { custom_error_loc } ->
-    ExplanationCustomError { custom_error_loc = f custom_error_loc }
+  | ExplanationCustomError { name; custom_error_loc } ->
+    ExplanationCustomError { name; custom_error_loc = f custom_error_loc }
   | ExplanationFunctionsWithStaticsToObject -> ExplanationFunctionsWithStaticsToObject
   | ExplanationInvariantSubtypingDueToMutableArray
       { lower_array_loc; upper_array_loc; lower_array_desc; upper_array_desc; upper_array_reason }
@@ -1865,12 +1865,13 @@ let rec convert_type_to_type_desc ~f =
     match use_op with
     | Op _ -> use_op
     | Frame
-        ( OpaqueTypeCustomErrorCompatibility { lower; upper; lower_t; upper_t; custom_error_loc },
+        ( OpaqueTypeCustomErrorCompatibility
+            { lower; upper; lower_t; upper_t; name; custom_error_loc },
           use_op
         ) ->
       Frame
         ( OpaqueTypeCustomErrorCompatibility
-            { lower; upper; lower_t = f lower_t; upper_t = f upper_t; custom_error_loc },
+            { lower; upper; lower_t = f lower_t; upper_t = f upper_t; name; custom_error_loc },
           map_use_op use_op
         )
     | Frame (frame, use_op) -> Frame (frame, map_use_op use_op)

src/typing/errors/flow_intermediate_error.ml

@@ -988,7 +988,8 @@ let rec make_intermediate_error :
           ~frame:FrameAnonymous
           ~custom_error_message
       | Frame
-          ( OpaqueTypeCustomErrorCompatibility { lower; upper; lower_t; upper_t; custom_error_loc },
+          ( OpaqueTypeCustomErrorCompatibility
+              { lower; upper; lower_t; upper_t; name; custom_error_loc },
             use_op
           ) ->
         let lower_desc =
@@ -1012,7 +1013,7 @@ let rec make_intermediate_error :
                }
             )
         in
-        let frames = ([], [ExplanationCustomError { custom_error_loc }]) in
+        let frames = ([], [ExplanationCustomError { name; custom_error_loc }]) in
         next_with_loc
           ~loc:(loc_of_aloc (loc_of_reason lower))
           ~frames
@@ -1912,7 +1913,7 @@ let to_printable_error :
         text " using ";
         code example;
       ]
-    | ExplanationCustomError { custom_error_loc } ->
+    | ExplanationCustomError { name; custom_error_loc } ->
       let loc = loc_of_aloc custom_error_loc in
       let custom_docs =
         Loc.source loc
@@ -1928,11 +1929,37 @@ let to_printable_error :
                )
            )
         |> Base.Option.bind ~f:(fun jsdoc ->
-               jsdoc |> Jsdoc.description |> Base.Option.map ~f:Base.String.strip
+               let description =
+                 jsdoc |> Jsdoc.description |> Base.Option.map ~f:Base.String.strip
+               in
+               let example =
+                 Base.List.Assoc.find
+                   (Jsdoc.unrecognized_tags jsdoc)
+                   ~equal:Base.String.equal
+                   "example"
+                 |> Base.Option.bind ~f:Base.Fn.id
+                 |> Base.Option.map ~f:Base.String.strip
+               in
+               match (description, example) with
+               | (None, None) -> None
+               | (Some d, None) -> Some [text "Description of "; code name; text ": "; text d]
+               | (None, Some e) -> Some [text "Example for "; code name; text ": "; code e]
+               | (Some d, Some e) ->
+                 Some
+                   [
+                     text "Description of ";
+                     code name;
+                     text ": ";
+                     text d;
+                     text ". Example for ";
+                     code name;
+                     text ": ";
+                     code e;
+                   ]
            )
       in
       (match custom_docs with
-      | Some d -> [text d]
+      | Some m -> m
       | None -> [text "See "; hardcoded_string_desc_ref "relevant docs" custom_error_loc])
     | ExplanationReactComponentPropsDeepReadOnly props_loc ->
       [

src/typing/errors/flow_intermediate_error_types.ml

@@ -308,7 +308,10 @@ type 'loc explanation =
       representation_type: string;
       casting_syntax: Options.CastingSyntax.t;
     }
-  | ExplanationCustomError of { custom_error_loc: 'loc }
+  | ExplanationCustomError of {
+      name: string;
+      custom_error_loc: 'loc;
+    }
   | ExplanationFunctionsWithStaticsToObject
   | ExplanationInvariantSubtypingDueToMutableArray of {
       lower_array_loc: 'loc;

src/typing/subtyping_kit.ml

@@ -1196,7 +1196,7 @@ module Make (Flow : INPUT) : OUTPUT = struct
         NominalT
           ( ru,
             {
-              nominal_id = Nominal.UserDefinedOpaqueTypeId _;
+              nominal_id = Nominal.UserDefinedOpaqueTypeId (_, name);
               underlying_t = Nominal.CustomError { t; custom_error_loc };
               _;
             }
@@ -1210,6 +1210,7 @@ module Make (Flow : INPUT) : OUTPUT = struct
                 upper = ru;
                 lower_t = TypeOrTypeDesc.Type l;
                 upper_t = TypeOrTypeDesc.Type u;
+                name;
                 custom_error_loc;
               },
             use_op

src/typing/type.ml

@@ -513,6 +513,7 @@ module rec TypeTerm : sig
         lower_t: 'loc TypeOrTypeDesc.t;
         upper_t: 'loc TypeOrTypeDesc.t;
         custom_error_loc: 'loc;
+        name: string;
       }
     | MappedTypeKeyCompatibility of {
         source_type: 'loc virtual_reason;

src/typing/typeUtil.ml

@@ -430,13 +430,15 @@ let rec mod_loc_of_virtual_use_op f =
       OpaqueTypeLowerBoundCompatibility { lower = mod_reason lower; upper = mod_reason upper }
     | OpaqueTypeUpperBoundCompatibility { lower; upper } ->
       OpaqueTypeUpperBoundCompatibility { lower = mod_reason lower; upper = mod_reason upper }
-    | OpaqueTypeCustomErrorCompatibility { lower; upper; lower_t; upper_t; custom_error_loc } ->
+    | OpaqueTypeCustomErrorCompatibility { lower; upper; lower_t; upper_t; name; custom_error_loc }
+      ->
       OpaqueTypeCustomErrorCompatibility
         {
           lower = mod_reason lower;
           upper = mod_reason upper;
           lower_t = TypeOrTypeDesc.map_loc f lower_t;
           upper_t = TypeOrTypeDesc.map_loc f upper_t;
+          name;
           custom_error_loc = f custom_error_loc;
         }
     | MappedTypeKeyCompatibility { source_type; mapped_type } ->