8

It turns out that Haddock does not render per-argument docs for type class methods:

class Foo a where

  foo
    :: Int -- ^ This string will be ignored by Haddock
    -> a

This causes certain issues for users of a library I maintain, because the methods in my case have quite lengthy signatures. I have always had the descriptions in the source formatted like that (certainly works for ordinary functions), but it turns out Haddock does not display them (and does not complain about them either).

Is there a way to display the per-argument docs with Haddock? Some workaround perhaps?

Mark Karpov
  • 7,499
  • 2
  • 27
  • 62
  • Are you open to making a major API change? If so, I could write a short answer on how to use a [single record argument](https://byorgey.wordpress.com/2010/04/03/haskell-anti-pattern-incremental-ad-hoc-parameter-abstraction/) for this. – Daniel Wagner Jun 29 '17 at 14:52
  • 1
    With Haddock 2.16.1, I get the per-argument doc rendered just fine, for standalone functions as well as for class methods. – leftaroundabout Jun 29 '17 at 15:51
  • @leftaroundabout, I'm running through 2.17.1, this: https://github.com/mrkkrp/megaparsec/blob/master/Text/Megaparsec.hs#L572-L575 for example, no per-argument docs. Can you spot a difference in markup, or is it a regression? – Mark Karpov Jun 29 '17 at 16:31
  • @DanielWagner, Major changes are possible, but they should not make the API emm... stylized just for the sake of a bit better docs. I'd like to keep it simple. – Mark Karpov Jun 29 '17 at 16:33
  • @leftaroundabout, Just confirmed, works with Haddock 2.16.1 but not with 2.17.1. Looks like a regression. – Mark Karpov Jun 29 '17 at 16:44

1 Answers1

3

OK, this was a regression. This thing should work (and worked in version 2.16.1), but stopped (2.17.1 and later).

I have reported this: https://github.com/haskell/haddock/issues/647, should be fixed in version 2.18 (you can see there is a PR for this already).

Mark Karpov
  • 7,499
  • 2
  • 27
  • 62