[base] Add usage advice for List and Dictionary Values

This change adds a comment that existing usages of base::ListValue
should be replaced by std::vector<base::Value>.

Bug: 646113
Change-Id: I7f2210f7f68d3bac5aa220041411e37db88ab097
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2502021Reviewed-by: Lei Zhang <thestig@chromium.org>
Reviewed-by: Karan Bhatia <karandeepb@chromium.org>
Commit-Queue: Jan Wilken Dörrie <jdoerrie@chromium.org>
Cr-Commit-Position: refs/heads/master@{#821230}

base/values.h

@@ -80,6 +80,15 @@ class Value;
 //     dict.SetKey("mykey", base::Value(foo));
 //     return dict;
 //   }
+//
+// The new design tries to avoid losing type information. Thus when migrating
+// off deprecated types, existing usages of base::ListValue should be replaced
+// by std::vector<base::Value>.
+//
+// Furthermore, existing usages of base::DictionaryValue should eventually be
+// replaced with base::flat_map<std::string, base::Value>. However, this
+// requires breaking changing the mapped type of Value::DictStorage first, and
+// thus usages of base::DictionaryValue should be kept for the time being.
 class BASE_EXPORT Value {
  public:
   using BlobStorage = std::vector<uint8_t>;
@@ -769,6 +778,7 @@ class BASE_EXPORT DictionaryValue : public Value {
 };
 
 // This type of Value represents a list of other Value values.
+// DEPRECATED: Use std::vector<base::Value> instead.
 class BASE_EXPORT ListValue : public Value {
  public:
   using const_iterator = ListView::const_iterator;