4

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.)

0 Answers0