Add notes on performance to Map and Set

src/libraries/OS-Independent/Data/Map.dcl

@@ -82,6 +82,12 @@ import StdClass
  * The abstract Map type provides the mapping.
  * For example "Map Int String" is a mapping "from" integers "to" strings.
  *
+ * Notes on performance:
+ * - For maps from `Int`, you can use Data.IntMap in many cases.
+ * - Avoid using tuples as keys, since strictness information is lost in their
+ *   `<` instance. Instead, define a (local) record with strict fields where
+ *   appropriate.
+ *
  * @var The key type on which the data structure is indexed.
  * @var The type of the values stored in the mapping.
  *

src/libraries/OS-Independent/Data/Set.dcl

@@ -76,6 +76,9 @@ from Data.Foldable import class Foldable
 /**
  * A `Set a` is an unordered, uncounted collection of values of type `a`.
  *
+ * Like with keys in `Map`, avoid tuple elements since this can be slow.
+ * Instead, define a (local) record with strict fields where appropriate.
+ *
  * @invariant integrity: A.s :: Set a | Eq, genShow{|*|}, gPrint{|*|} a:
  *     // Check that the data structure is still correct.
  *     name "no_duplicates" (no_duplicates s) /\