[GHC] #14357: Document deriving strategies fully
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Keywords: | Operating System: Unknown/Multiple Architecture: | Type of failure: None/Unknown Unknown/Multiple | Test Case: | Blocked By: Blocking: | Related Tickets: Differential Rev(s): | Wiki Page: -------------------------------------+------------------------------------- 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? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (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 [https://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/DerivingStrategies... here] into something short and snappy!) So I don't know what you're expecting the users' guide to say in this regard. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (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... #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. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by RyanGlScott): * keywords: => deriving Comment: 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... #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). -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (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? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:4 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by RyanGlScott): Replying to [comment:4 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? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by nomeata): Not necessarily :-) (at least not right now). I will, however, not blame anyone else for not doing this right now either. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:6 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (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. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:7 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: new Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by nomeata): Ok ok, I’ll give it a shot :-) -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:8 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully
-------------------------------------+-------------------------------------
Reporter: nomeata | Owner: (none)
Type: task | Status: new
Priority: normal | Milestone:
Component: Documentation | Version: 8.2.1
Resolution: | Keywords: deriving
Operating System: Unknown/Multiple | Architecture:
| Unknown/Multiple
Type of failure: None/Unknown | Test Case:
Blocked By: | Blocking:
Related Tickets: | Differential Rev(s):
Wiki Page: |
-------------------------------------+-------------------------------------
Comment (by Joachim Breitner
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: closed Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: fixed | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by nomeata): * status: new => closed * resolution: => fixed Comment: 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`). -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:10 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14357: Document deriving strategies fully -------------------------------------+------------------------------------- Reporter: nomeata | Owner: (none) Type: task | Status: closed Priority: normal | Milestone: Component: Documentation | Version: 8.2.1 Resolution: fixed | Keywords: deriving Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by RyanGlScott): Thanks, Joachim! That patch looks great. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14357#comment:11 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
participants (1)
-
GHC