Comments on components of a tuple, for argument or return types.

[ghc-mirror]

Original reporter: david.waern@

[ghc-mirror]

Original reporter: anonymous

Is the same as #23 ?

[pseudometric]

This is something I would very much like. I have the following type signature:

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

Making the comments on the tuple components Haddock annotations yields a Haddock parse error. The return type is completely unreadable in the documentation; it stretches off the screen, pulling the comments of the argument types off-screen with it, and makes the pullout “Synopsis” bar useless as well.

[Fuuzetsu]

The biggest problem with this (and issues like this one, such as docummenting each argument to constructors, #23) is that the changes have to be made in the GHC parser which is quite a large undertaking. While I eventually do hope to get around to these issues, I would certainly not hold my breath waiting for those as it will certainly not be out before GHC 7.10 timeline and probably even longer (unless someone sends patches before that).

Did you consider using a record as a workaround? You can document each field separately although it's not exactly the same result: I imagine you want ‘inline’ comments.

I will certainly keep this in mind when I inevitably dive into the GHC parser bits.

[pseudometric]

Thanks for taking this into consideration. It’s too bad it’s so involved; otherwise, I’d volunteer to hack at it myself.

I have in fact now converted my code to use separate record types in place of the tuples in the return types (I have a whole library of routines with similar types). I resisted doing that just to appease Haddock, but there’s some independent value in it anyway: if the user actually passes those values around rather than just pattern-matching on them when calling the routine, then tuples can be cumbersome and less safe than distinct product types. As you say, the display is still not exactly what I’d like: it would be nice to have the inline comments, and also the types in the record are not lined up vertically. And having the full return type effectively split up into two separate blocks one has to read — and which are formatted differently — is not as nice. But there are pros and cons, and this will work OK. I still do think it would be nice to have this feature, when it’s possible to get to it.