[GHC] #12372: bug: documentation for Control.Monad.guard not useful after AMP
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: Type: bug | Status: new Priority: normal | Milestone: Component: | Version: 8.0.1 libraries/base | Keywords: | Operating System: Unknown/Multiple Architecture: | Type of failure: Documentation Unknown/Multiple | bug Test Case: | Blocked By: Blocking: | Related Tickets: Differential Rev(s): | Wiki Page: -------------------------------------+------------------------------------- Since the AMP refactor, the documentation for `Control.Monad.guard` [1] is no longer useful for beginners. It simply gives the definition of `guard`, but in prose: {{{ guard b is pure () if b is True, and empty if b is False. }}} (and better to just use Haskell instead of prose here, no?) To use `guard` in a `MonadPlus`, you now need to know that `Alternative` is a super class of `MonadPlus`, and that `mzero = zero`. The documentation [2] for `MonadPlus` doens't mention `mzero = zero` in the default definition -- you must look at the source for that -- and the docs for `guard` don't mention `MonadPlus`. The documentation for `Control.Monad.guard` should suggest use with `MonadPlus`, and give an example (compare with the very helpful example for `Control.Monad.when`). A non-monadic example would also be useful. [1] https://hackage.haskell.org/package/base-4.9.0.0/docs/Control- Monad.html#v:guard [2] https://hackage.haskell.org/package/base-4.9.0.0/docs/Control- Monad.html#t:MonadPlus -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: Type: bug | Status: new Priority: normal | Milestone: Component: libraries/base | Version: 8.0.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by simonpj): * cc: ekmett, core-libraries-committee@… (added) Comment: Thanks. This is a question for the Core Libraries Committee, cc'd -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: Type: bug | Status: new Priority: normal | Milestone: Component: libraries/base | Version: 8.0.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by ekmett): Do you have an example of the text you'd prefer? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: Type: bug | Status: new Priority: normal | Milestone: Component: libraries/base | Version: 8.0.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by ntc2): Replying to [comment:2 ekmett]:
Do you have an example of the text you'd prefer?
Not off the top of my head. I'll think about this and get back to you. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: Type: bug | Status: infoneeded Priority: normal | Milestone: Component: libraries/base | Version: 8.0.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by bgamari): * status: new => infoneeded Comment: ntc2, any word on this? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:4 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: Type: bug | Status: infoneeded Priority: normal | Milestone: Component: libraries/base | Version: 8.0.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by ntc2): Replying to [comment:4 bgamari]:
ntc2, any word on this?
So, I'm only familiar with `MonadPlus` examples. E.g. {{{ safeDivision :: (Eq a, Fractional a, MonadPlus m) => a -> a -> m a safeDivison n d = do guard (d /= 0) return (n / d) ghci> safeDivision 3 0 :: Maybe Double Nothing ghci> safeDivision 3 2 :: Maybe Double Just 1.5 }}} Now, it turns out I can also write that example using `Alternative`, i.e. {{{ safeDivisionA :: (Eq a, Fractional a, Alternative f) => a -> a -> f a safeDivisionA n d = guard (d /= 0) *> pure (n / d) ghci> safeDivisionA 3 0 :: Maybe Double Nothing ghci> safeDivisionA 3 2 :: Maybe Double Just 1.5 }}} but the default `Alternatives` I know are exactly the `MonadPlus` types, i.e. `[]` and `Maybe`, so I don't see what I've gained here (and in practice I think I'd just use `Maybe` here). So, I think a `MonadPlus` example like `safeDivision` would be useful. An example that only makes use of the weaker `Alternative` assumption might also be useful, but I don't have one. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: (none) Type: bug | Status: infoneeded Priority: normal | Milestone: Component: libraries/base | Version: 8.0.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by ntc2): Fix here: https://phabricator.haskell.org/D4258 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:6 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP
-------------------------------------+-------------------------------------
Reporter: ntc2 | Owner: (none)
Type: bug | Status: infoneeded
Priority: normal | Milestone:
Component: libraries/base | Version: 8.0.1
Resolution: | Keywords:
Operating System: Unknown/Multiple | Architecture:
Type of failure: Documentation | Unknown/Multiple
bug | Test Case:
Blocked By: | Blocking:
Related Tickets: | Differential Rev(s):
Wiki Page: |
-------------------------------------+-------------------------------------
Comment (by Ben Gamari
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: (none) Type: bug | Status: closed Priority: normal | Milestone: Component: libraries/base | Version: 8.0.1 Resolution: fixed | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by ntc2): * status: infoneeded => closed * resolution: => fixed -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:8 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: (none) Type: bug | Status: closed Priority: normal | Milestone: 8.4.1 Component: libraries/base | Version: 8.0.1 Resolution: fixed | Keywords: Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by bgamari): * milestone: => 8.4.1 Comment: Merged. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372#comment:9 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
participants (1)
-
GHC