I have Haskell function signature with a long tuple in it, which I am trying to annotate for Haddock:
gssAcceptSecContext ::
Maybe GssCtxId -- ^ context_handle
-> Maybe GssCredId -- ^ acceptor_cred_handle
-> GssToken -- ^ input_token_buffer
-> Maybe GssChannelBindings -- ^ input_chan_bindings
-> IO (Either GssError -- failure: error message
-- success: return values
(GssCtxId, -- context_handle
Maybe GssToken, -- output_token
Bool, -- continue? (GSS_S_CONTINUE_NEEDED is set)
GssName, -- src_name
GssOid, -- mech_type
[GssService], -- ret_flags
Int, -- time_rec
Maybe GssCredId)) -- delegated_cred_handle
If I convert the comments on the tuple members to Haddock markup (-- ^
, as with the earlier argument types), Haddock bails with a parsing error. I’ve found a few comments suggesting that this is just a limitation and there’s nothing to do about it; is that so? It’s pretty bad; the documentation and synopsis bar both run off the edge of the screen and are unreadable. I don’t really want to introduce a separate type in place of the tuple just to satisfy Haddock.
Thanks!
(Update: there’s an open Haddock feature request which appears to confirm that this is not currently supported; I’ve added my +1 there — but I’m interested if anyone has a patch or workaround.)