Allow putting Haddocks on derived instances
ClosedPublic

Authored by RyanGlScott on May 4 2016, 9:51 PM.

Details

Summary

Currently, one can document top-level instance declarations, but
derived instances (both those in deriving clauses and standalone deriving
instances) do not enjoy the same privilege. This makes the necessary
changes to the parser to enable attaching Haddock comments for derived
instances.

Fixes Trac #11768.

Test Plan

./validate

Diff Detail

Repository
rGHC Glasgow Haskell Compiler
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
RyanGlScott retitled this revision from to Allow putting Haddocks on derived instances.May 4 2016, 9:51 PM
RyanGlScott updated this object.
RyanGlScott edited the test plan for this revision. (Show Details)
RyanGlScott added reviewers: bgamari, hvr, austin.
RyanGlScott updated the Trac tickets for this revision.
bgamari added a comment.EditedMay 5 2016, 2:48 AM

Fantastic! Thanks for picking this up.

It seems like you could use a similar strategy to handle standard non-record fields this way too,

data Foo = Foo      -- ^ A foo
             Int    -- ^ how big is the foot
             String -- ^ the name of the foo

I suppose the trouble here is that this would change the current meaning of some doc comments (since "the name of the foo" would currently be applied to the Foo tycon.

I suppose the trouble here is that this would change the current meaning of some doc comments (since "the name of the foo" would currently be applied to the Foo tycon.

Indeed. I'm loathe to make a breaking change to the way Haddock works here, since that would affect the way comments are rendered for a good amount of data constructors in the wild. And in any case, this seems like an orthogonal concern - perhaps we should open a separate Trac issue for this?

austin accepted this revision.May 9 2016, 2:33 PM

I suppose the trouble here is that this would change the current meaning of some doc comments (since "the name of the foo" would currently be applied to the Foo tycon.

Indeed. I'm loathe to make a breaking change to the way Haddock works here, since that would affect the way comments are rendered for a good amount of data constructors in the wild. And in any case, this seems like an orthogonal concern - perhaps we should open a separate Trac issue for this?

Yes, that's a bit of a contentious one I'm sure. But in the mean time, this looks good to me (and so does the associated Haddock patch). It does need release notes though, but that's blocked on D2066 and we can let it slide for now.

This revision is now accepted and ready to land.May 9 2016, 2:33 PM
hvr awarded a token.May 9 2016, 3:05 PM
This revision was automatically updated to reflect the committed changes.

Indeed. I'm loathe to make a breaking change to the way Haddock works here, since that would affect the way comments are rendered for a good amount of data constructors in the wild. And in any case, this seems like an orthogonal concern - perhaps we should open a separate Trac issue for this?

Indeed it is quite orthogonal, it just came to happened to pop into mind. I've opened Trac #12050 to track this.