Documentation: how do `is`, `isn't`, and `matching` work?

[marick]

I'm a newbie writing documentation for newbies, in this case about Prisms.

Question 1: There are three functions that seem to be about checking if a value is the one a prism focuses on: is, isn't, and matching. matching is the only one I can get to work. How does one use is and isn't?

Question 2: Now let's consider this type:

data Fill
  = Solid Color
  | LinearGradient Color Color Percent
  | RadialGradient Color Color Point
  | NoFill

Let's suppose I create a prism that selects out the Solid case:

chooseSolidM fill =
  case fill of
    Solid x -> Just x
    _ -> Nothing

solidM = prism' Solid chooseSolidM

Given values solid and linear, matching gives me these results:

> matching solidM linear
(Left (LinearGradient rgba 255 255 255 1.0 rgba 0 0 0 1.0 3.3%))

> matching solidM solid
(Right rgba 255 255 255 1.0)

That seems sensible: If the match is "right", the value is extracted; otherwise, you are "left" with the original value. But let's look at what happens when we look at a specific (only) Solid value:

whiteSolid =
  only (Solid Color.white)

matching works differently:

> matching whiteSolid (Solid Color.black)
(Left (Solid rgba 0 0 0 1.0))

> matching whiteSolid (Solid Color.white)
(Right unit)

I understand why the types dictate those results, but I don't understand the inconsistency between how Prisms created with prism' (or prism) and those created with only behave. Why don't they both provide the failing value?