Haddock: Documentation for instance functions with quirks replaced by default class documentation

Question

Consider the following example:

instance (Monad m) => MonadState s (ChronoT s e m) where

    -- | Returns the present-day state.
    get   = ChronoT $ do
        (ChronoS _ s _) <- get
        return s

    -- | Set the present-day state directly, erasing the past and future for
    --   safety. See also 'paradox'.
    put x = ChronoT $ do
        (ChronoS _ _ _) <- get
        put $ mkChronoS x

When run through haddock, the functions get and put show up, but they are using the default documentation from MonadState. How do I include my own documentation for them in my module?

(You can see what I mean by running cabal haddock over the repo here)

Answer 1

You can't.

What you can do is document your instance.

-- | You can have a brief description here
instance (Monad m) => MonadState s (ChronoT s e m) where
…

This will make the description show up to the side of the instances box generated. This should preferably be brief but it does let you do things such as point the user to documentation of the functions implementing the fields if you really need to, like the commenter on the question suggests.

Personally, I think that it doesn't make much sense to document each field like this: what the fields are meant to do should be clear from documentation of the class definition and the comment on the instance.