Opened 3 years ago

Closed 2 years ago

#13175 closed task (fixed)

Documenting what can be derived 'out of the box' by GHC's "deriving"

Reported by: carette Owned by:
Priority: normal Milestone: 8.4.1
Component: Documentation Version: 8.0.1
Keywords: newcomer, deriving Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: Documentation bug Test Case:
Blocked By: Blocking:
Related Tickets: Differential Rev(s):
Wiki Page:

Description

Nowhere in the documentation is it clearly stated which classes can be derived (assuming extensions as necessary) by GHC's "deriving" mechanism. As determined by reading the sources, this appears to be

  • Bounded, Enum, Eq, Ix, Ord, Read, Show, Functor, Foldable, Traversable, Generic, Generic1, Data, Lift.

This was discussed on haskell-cafe -- see https://mail.haskell.org/pipermail/haskell-cafe/2016-October/125379.html.

PS: I would be willing to fix this myself, if only I knew *where* to insert that information so that it is easily findable!

Change History (10)

comment:1 Changed 3 years ago by simonpj

PS: I would be willing to fix this myself, if only I knew *where* to insert that information so that it is easily findable!

Thank you! But you are the best person to say where you'd expect to find it, because presumably you looked :-). I'd love a patch.

comment:2 Changed 3 years ago by carette

Unfortunately I 'looked' via Google. I expected to find it that way... Once the information is somewhere, I will then expect that that will indeed work. But, in the meantime, I am still at a loss as to where to put it.

One of the problems is that when you search for "GHC" and "deriving", the principal hits are to section 7.5 of the manual (https://downloads.haskell.org/~ghc/7.8.4/docs/html/users_guide/deriving.html) which documents the extensions to this mechanism. If you dig really (really!) hard, you eventually find section 4.3.3 of the Haskell 98 report (https://www.haskell.org/onlinereport/decls.html#derived-decls) which documents "deriving" (the 2010 report's 4.3.3 is essentially identical). But Google doesn't seem to like that much, so it doesn't show up.

But the list in those reports is not the same as the list above!

So I am still at a loss as to where to put this. GHC's own documentation does not define "deriving" (because the Haskell reports already do), which would have been my first thought. So maybe in 7.5 somewhere?

comment:3 Changed 3 years ago by RyanGlScott

Thank you for the report.

So you're correct in that the list of stock derivable classes is not so Google-able (where stock is terminology that I use in the upcoming DerivingStrategies GHC extension, documented here). That DerivingStrategies wiki page information does need to be in a more public location, I admit.

The users' guide actually does list all of the stock derivable classes that are available via GHC extensions in http://downloads.haskell.org/~ghc/8.0.1/docs/html/users_guide/glasgow_exts.html#deriving-instances-of-extra-classes-data-etc. But we don't currently list the stock derivable classes that were already mentioned in the Haskell Report (Bounded, Enum, Ix, Eq, Ord, Read, and Show).

If I recapped those classes in that section of the users' guide, would that work for you?

comment:4 Changed 3 years ago by carette

The DerivingStrategies web page is actually easier to find (I referenced it when I first asked the question https://mail.haskell.org/pipermail/haskell-cafe/2016-October/125378.html).

Yes, recapping the stock derivable instances along with the extras that GHC also implements would work for me. Perhaps in the prelude to 9.6 (i.e. before 9.6.1)?

comment:5 Changed 3 years ago by RyanGlScott

That sounds agreeable to me!

Do you want to take a crack at fixing the users' guide? The relevant part of the codebase that you'd have to change is here: http://git.haskell.org/ghc.git/blob/9fd87ef8a16fbbce35205ae63d75d239bb575ccc:/docs/users_guide/glasgow_exts.rst#l3192 And if you want to preview what your changes look like, you can either build just the docs (see these instructions), or you can fork GHC on GitHub and view a rendered version of docs/users_guide/glasgow_exts.rst directly (for example, see this).

comment:6 Changed 3 years ago by carette

Yes, I'll give it a crack. Does this mean that I should 'own' this ticket?

comment:7 in reply to:  6 Changed 3 years ago by RyanGlScott

Replying to carette:

Yes, I'll give it a crack. Does this mean that I should 'own' this ticket?

Sure, go ahead.

comment:8 Changed 2 years ago by RyanGlScott

Keywords: newcomer added

comment:9 Changed 2 years ago by RyanGlScott

Keywords: deriving added

comment:10 Changed 2 years ago by RyanGlScott

Milestone: 8.4.1
Resolution: fixed
Status: newclosed

I believe this can be considered fixed as of 317aa966b3d89e45227a5870feba339e34d77a18. The beginning of the users' guide section on GHC's extensions to deriving now mentions:

* In Haskell 98, the only derivable classes are ``Eq``,
  ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and ``Show``. `Various
  langauge extensions <#deriving-extra>`__ extend this list.

The deriving-extra section then proceeds to mention each of the remaining classes that are stock derivable.

Note: See TracTickets for help on using tickets.