## bug: documentation for Control.Monad.guard not useful after AMP

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

## Trac metadata

Trac field | Value |
---|---|

Version | 8.0.1 |

Type | Bug |

TypeOfFailure | OtherFailure |

Priority | normal |

Resolution | Unresolved |

Component | libraries/base |

Test case | |

Differential revisions | |

BlockedBy | |

Related | |

Blocking | |

CC | |

Operating system | |

Architecture |