[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 <ben@…>): In [changeset:"6847c6bf5777eaf507f1cef28c1fc75a2c68bdef/ghc" 6847c6b/ghc]: {{{ #!CommitTicketReference repository="ghc" revision="6847c6bf5777eaf507f1cef28c1fc75a2c68bdef" Improve Control.Monad.guard and Control.Monad.MonadPlus docs This fixes Issue #12372: documentation for Control.Monad.guard not useful after AMP. Reviewers: hvr, bgamari Reviewed By: bgamari Subscribers: rwbarton, thomie, carter Differential Revision: https://phabricator.haskell.org/D4258 }}} -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/12372#comment:7> 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: 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