Comments inside record field types

[ghc-mirror]

Original reporter: naesten@

for some reason,

newtype P a = P { runP ::
                        String          -- ^ Input string
                     -> Int             -- ^ Current column
                     -> Int             -- ^ Current line
                     -> SrcLoc          -- ^ Location of last token read
                     -> ParseState      -- ^ Layout info.
                     -> ParseMode       -- ^ Parse parameters
                     -> ParseStatus a
                }

fails to parse, but

newtype P a = P { runP ::
                        String          -- Input string
                     -> Int             -- Current column
                     -> Int             -- Current line
                     -> SrcLoc          -- Location of last token read
                     -> ParseState      -- Layout info.
                     -> ParseMode       -- Parse parameters
                     -> ParseStatus a
                }

parses fine.

[ghc-mirror]

Original reporter: david.waern@

This is just not supported by the current grammar. It would be nice to support it, but I wonder how, since it is possible to comment record fields using the -- ^ notation which would clash with commenting the result type.

Perhaps we should only allow comments on record fields to exist on the lines before or after the field. This would make it possible to comment the type (or parts of the type) like you did in the example.

[ghc-mirror]

Original reporter: naesten@

Yeah, I figured that out soon after posting this ;-). Personally, I'd be happy with this requiring the function type to be in parens. (A nicer parse error would also be helpful.) I guess this bug is misnamed ... did you already make a bug about this?

[ghc-mirror]

Original reporter: david.waern@

Replying to [comment:2 SamB]:

Yeah, I figured that out soon after posting this ;-). Personally, I'd be happy with this requiring the function type to be in parens.

Hmm, that's a bit inconsistent though, since comments on types of function definitions works exactly the opposite way.

(A nicer parse error would also be helpful.) I guess this bug is misnamed ... did you already make a bug about this?

Nope, there's no such bug report. I'd rather call it an enhancement though, since the comments-on-types stuff has a very limited design currently and was not supposed to do this. It for example only supports comments on function arguments at the highest level. I think it would be good to try to generalize the design a little bit to support cases like this and more.

[sjakobi]

Duplicate of #23?

[harpocrates]

Duplicate of #23?

Definitely not - this is much simpler! In fact, I think this is quite achievable even today. We just need to tweak the ghc grammar to replace on sigtype with a sigtypedoc. The ambiguity pointed out above is the main problem.

This is just not supported by the current grammar. It would be nice to support it, but I wonder how, since it is possible to comment record fields using the -- ^ notation which would clash with commenting the result type.

I think it would be quite reasonable to take the same approach to resolving this ambiguity as we take for constructor arguments.

I might take a stab at this once the Hi Haddock changes land in GHC.

[schell]

Gently pinging this as I ran into this today. I'd like to document my record like this:

data MyRecord m
  = MyRecord
  { -- | A function that does stuff. 
    myFunction 
      :: V2 Int 
      -- ^ The position  
      -> m SomeType 
      -- ^ The return type
  }

I don't have all the context, but if a comment is found inside the type of a record field, then I think it's safe to assume that the author's intent is to document those field's types, including return value, instead of the field itself. The field itself can still be documented using -- |. This is how GADTs are documented so I was surprised to find that records don't work this way.

Anyway - thanks for these great tools!

[harpocrates]

Thanks for the ping - this is still very much on my radar. Hi Haddock is not yet done, though it hopefully will be come end of next month! Once that wraps up, there will be more time to work on this sort of enhancement.

[sirlensalot]

Is this something a noob contrib like myself can help with? Just lost significant time chasing this problem down. FWIW it's actually pretty hard to find out about this limitation, it might be nice to put a gotcha like this in the README or somewhere easy to find.

[Kleidukos]

Is this something a noob contrib like myself can help with? Just lost significant time chasing this problem down. FWIW it's actually pretty hard to find out about this limitation, it might be nice to put a gotcha like this in the README or somewhere easy to find.

A PR adding this limitation for the ReST docs would be welcome. Tag me in it so that I can provide a timely review.