@@ -171,8 +171,8 @@ name .= value = (name, toJSON value)
171171{-# INLINE (.=) #-}
172172
173173-- | Construct an optional 'Pair' from a key and a Maybe value. If
174−-- the value is Nothing, then it is omitted altogether from the
175−-- resulting Object.
174+-- the value is Nothing, the Pair's value is set to Missing, which
175+-- 'object' will remove from the resulting 'Object'.
176176(.=?) :: ToJSON a => Text -> Maybe a -> Pair
177177name .=? Nothing = (name, Missing)
178178name .=? Just value = (name, toJSON value)
@@ -214,9 +214,10 @@ obj .:? key = case M.lookup key obj of
214214 Just v -> parseJSON v
215215{-# INLINE (.:?) #-}
216216
217−-- | Traverse a object heirarchy.
218−-- This is useful for traversing a JSON object to get to an
219−-- appropriate place before parsing.
217+-- | Traverse a object heirarchy. This is useful for traversing a
218+-- JSON object to get to an appropriate place before parsing. If a
219+-- key is not found or it encounters a non-'Object' node, then it
220+-- returns 'Missing'.
220221(./) :: Value -> Text -> Value
221222(Object obj) ./ key = case M.lookup key obj of
222223 Nothing -> Missing
@@ -224,8 +225,9 @@ obj .:? key = case M.lookup key obj of
224225_ ./ _ = Missing
225226{-# INLINE (./) #-}
226227
227−-- | Create a 'Value' from a list of name\/value 'Pair's. If duplicate
228−-- keys arise, earlier keys and their associated values win.
228+-- | Create a 'Value' from a list of name\/value 'Pair's. If
229+-- duplicate keys arise, earlier keys and their associated values win.
230+-- Missing values will be excluded from the resulting 'Object'.
229231object :: [Pair] -> Value
230232object = Object . M.fromList . filter (notmissing . snd)
231233 where notmissing Missing = False