Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#14357 closed task (fixed)

Document deriving strategies fully

Reported by: nomeata Owned by:
Priority: normal Milestone:
Component: Documentation Version: 8.2.1
Keywords: deriving Cc: RyanGlScott
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: None/Unknown Test Case:
Blocked By: Blocking:
Related Tickets: Differential Rev(s):
Wiki Page:

Description

The users’ guide currently sais in the section on DerivingStrategies:

If an explicit deriving strategy is not given, GHC has an algorithm for determining how it will actually derive an instance. For brevity, the algorithm is omitted here. You can read the full algorithm at Wiki page.

I think this is doing our users a disservice: They want to rely on the guide to have authorative, concise and clear information. The wiki page contains too much stuff that is confusing for users (Alternative syntax, rationales etc.)

(Also, the link in the manual is wrong).

Ryan, do you agree and are you available to put the relevant bits into the manual?

Change History (11)

comment:1 Changed 2 years ago by RyanGlScott

I agree that the "wiki page contains too much stuff that is confusing for users", which is precisely why I didn't inline the gory details into the users' guide in the first place, and left a link for adventurous readers. But I consider the algorithm for choosing when GHC will default to a particular strategy to be an especially gory giblet. (If you don't believe me, try to condense the information here into something short and snappy!) So I don't know what you're expecting the users' guide to say in this regard.

comment:2 Changed 2 years ago by nomeata

Sure, good documentation is tricky :-)

I would have found the enumeration at the beginning of the wiki section already quite useful.

Also note that this describes what happens without DerivingStrategies. So maybe it should not be documented under this language extension… Bits of the information that is missing here are scattered throughout the documentation, e.g. https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#precise-gnd-specification states:

Lastly, all of this applies only for classes other than Read, Show, Typeable, and Data, for which the stock derivation applies (section 4.3.3. of the Haskell Report).

So maybe there should be a general section that describes GHC’s approach to deriving more general, and gives an overview that spans the various pragmas.

comment:3 Changed 2 years ago by RyanGlScott

Keywords: deriving added

OK. What you are describing sounds a lot like #13175, yes? We already have quite an extensive overview of all the various Deriving pragmas (see https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#deriving-instances-of-extra-classes-data-etc). All that's missing is a blurb that mentions the other stock derivable classes (and of course, a link to deriving strategies section that explains what "stock" means).

comment:4 Changed 2 years ago by nomeata

Yes, maybe that’d be sufficient. I think I’d also like to know which stock instances are derived as such for newtypes, and which are derived by using the newtype strategy, but I guess that information can also be found (“C is not Read, Show, Typeable, or Data. These classes should not “look through” the type or its constructor. You can still derive these classes for a newtype, but it happens in the usual way, not via this new mechanism.”).

So maybe, all the information is already present in the manual, in which case the reference to the wiki can be removed?

comment:5 in reply to:  4 Changed 2 years ago by RyanGlScott

Replying to nomeata:

So maybe, all the information is already present in the manual, in which case the reference to the wiki can be removed?

Sounds good to me. Do you want to take a crack at implementing this?

comment:6 Changed 2 years ago by nomeata

Not necessarily :-) (at least not right now).

I will, however, not blame anyone else for not doing this right now either.

comment:7 Changed 2 years ago by RyanGlScott

OK. I ask since you seem to have a clear vision of what particular phrasing to add here, so it would probably be much more direct to have you write this down than for someone like me to guess what you'd like to see.

comment:8 Changed 2 years ago by nomeata

Ok ok, I’ll give it a shot :-)

comment:9 Changed 2 years ago by Joachim Breitner <mail@…>

In 317aa966/ghc:

Improve user’s guide around deriving

In particular:
 * add an intro to “10.6. Extensions to the “deriving” mechanism” giving
   an overview,
 * make the various sections on `-XDerivingFoo` subsections of
   “10.6.3. Deriving instances of extra classes (Data, etc.)”
 * Move the reference anchors for the various `DerivingFoo` extensions
   to a more appropriate spot.
 * Add subsection “10.6.6.1. Default deriving strategy” to the
   deriving section (#14357)

comment:10 Changed 2 years ago by nomeata

Resolution: fixed
Status: newclosed

Ok, I gave it a shot. Ryan, I’d appreciate if you could check that I did not introduce any wrong facts there (and feel free to fix any mistakes or do any other kind of improvement directly in master).

comment:11 Changed 2 years ago by RyanGlScott

Thanks, Joachim! That patch looks great.

Note: See TracTickets for help on using tickets.