On Dec 15, 2011, at 4:29 PM, Chris Wong wrote:
Okay, so how about the following as a user narrative for some and many?
...
I was in the middle of writing my own version of Applicative when I stumbled on this intense debate. Here's what I wrote for the documentation:
class (Applicative f, Monoid f) => Alternative f where -- | Keep repeating the action (consuming its values) until it fails, and then return the values consumed. -- -- [Warning]: This is only defined for actions that eventually fail -- after being performed repeatedly, such as parsing. For pure values such -- as 'Maybe', this will cause an infinite loop. some :: f a -> f [a] some v = ...
-- | Similar to 'many', but if no values are consumed it returns 'empty' instead of @f []@. -- -- [Warning]: This is only defined for actions that eventually fail -- after being performed repeatedly, such as parsing. For pure values such -- as 'Maybe', this will cause an infinite loop. many :: f a -> f [a] many v = ...
Warnings are repeated for emphasis :)
I think that merely putting up documentation along these lines would be a huge improvement, though it should also contain the formal definitions from the old documentation in it somewhere as well. Cheers, Greg