[base] Extend Guidance for DictionaryValue
This change updates the guidance on top of values.h to prefer
base::flat_map<std::string, base::Value> over base::DictionaryValue.
Bug: 646113
Change-Id: Ib02ad787068b3f89ae56ea13c4044338eb703437
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2509576
Reviewed-by: Lei Zhang <[email protected]>
Commit-Queue: Jan Wilken Dörrie <[email protected]>
Cr-Commit-Position: refs/heads/master@{#825281}
diff --git a/base/values.h b/base/values.h
index fbaa369..1e2d0e5 100644
--- a/base/values.h
+++ b/base/values.h
@@ -83,12 +83,22 @@
//
// 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>.
+// by std::vector<base::Value>, and existing usages of base::DictionaryValue
+// should be replaced with base::flat_map<std::string, 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.
+// OLD WAY:
+//
+// void AlwaysTakesList(std::unique_ptr<base::ListValue> list);
+// void AlwaysTakesDict(std::unique_ptr<base::DictionaryValue> dict);
+//
+// NEW WAY:
+//
+// void AlwaysTakesList(std::vector<base::Value> list);
+// void AlwaysTakesDict(base::flat_map<std::string, base::Value> dict);
+//
+// Migrating code will require conversions on API boundaries. This can be done
+// cheaply by making use of overloaded base::Value constructors and the
+// Value::TakeList() and Value::TakeDict() APIs.
class BASE_EXPORT Value {
public:
using BlobStorage = std::vector<uint8_t>;
