@@ -318,17 +318,52 @@ instance KeyValue Pair where
318318-- Classes and types for map keys
319319-------------------------------------------------------------------------------
320320
321+-- | Typeclass for types that can be used as the key of a map-like container
322+-- (like 'Map' or 'HashMap'). For example, since 'Text' has a 'ToJSONKey'
323+-- instance and 'Char' has a 'ToJSON' instance, we can encode a value of
324+-- type 'Map' 'Text' 'Char':
325+--
326+-- >>> LBC8.putStrLn $ encode $ Map.fromList [("foo" :: Text, 'a')]
327+-- {"foo":"a"}
328+--
329+-- Since 'Int' also has a 'ToJSONKey' instance, we can similarly write:
330+--
331+-- >>> LBC8.putStrLn $ encode $ Map.fromList [(5 :: Int, 'a')]
332+-- {"5":"a"}
333+--
334+-- JSON documents only accept strings as object keys. For any type
335+-- from @base@ that has a natural textual representation, it can be
336+-- expected that its 'ToJSONKey' instance will choose that representation.
337+--
338+-- For data types that lack a natural textual representation, an alternative
339+-- is provided. The map-like container is represented as a JSON array
340+-- instead of a JSON object. Each value in the array is an array with
341+-- exactly two values. The first is the key and the second is the value.
342+--
343+-- For example, values of type '[Text]' cannot be encoded to a
344+-- string, so a 'Map' with keys of type '[Text]' is encoded as follows:
345+--
346+-- >>> LBC8.putStrLn $ encode $ Map.fromList [(["foo","bar","baz" :: Text], 'a')]
347+-- [[["foo","bar","baz"],"a"]]
348+--
349+-- The default implementation of 'ToJSONKey' will choose this method of
350+-- encoding a key, using the 'ToJSON' instance of the type.
321351class ToJSONKey a where
352+ -- | Provides a way to use a data type as the key for a map-like
353+ -- container.
322354 toJSONKey :: ToJSONKeyFunction a
323355 default toJSONKey :: ToJSON a => ToJSONKeyFunction a
324356 toJSONKey = ToJSONKeyValue (toJSON, toEncoding)
357+ -- | This is similar in spirit to the 'showsList' method of 'Show'.
358+ -- It makes it possible to give 'String' keys special treatment
359+ -- without using @OverlappingInstances@.
325360 toJSONKeyList :: ToJSONKeyFunction [a]
326361 default toJSONKeyList :: ToJSON a => ToJSONKeyFunction [a]
327362 toJSONKeyList = ToJSONKeyValue (toJSON, toEncoding)
328363
329364data ToJSONKeyFunction a
330− = ToJSONKeyText (a -> Text, a -> Encoding)
331− | ToJSONKeyValue (a -> Value, a -> Encoding)
365+ = ToJSONKeyText (a -> Text, a -> Encoding) -- ^ key is encoded to string, produces object
366+ | ToJSONKeyValue (a -> Value, a -> Encoding) -- ^ key is encoded to value, produces array
332367
333368contramapToJSONKeyFunction :: (b -> a) -> ToJSONKeyFunction a -> ToJSONKeyFunction b
334369contramapToJSONKeyFunction h x = case x of