[GHC] #13003: improve documentation for typed TH and make it more discoverable
#13003: improve documentation for typed TH and make it more discoverable -------------------------------------+------------------------------------- Reporter: carter | Owner: Type: bug | Status: new Priority: normal | Milestone: 8.2.1 Component: Documentation | Version: 8.0.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: -------------------------------------+------------------------------------- theres quite a sparsity of documentation and dearth of discoverability for typed TH in the Template Haskell Library haddocks and the GHC manual, this probably wouldn't be much work to make it vastly better. one specific two course of action might be a) adding to the template haskell library a module `Language.Haskell.TH.Typed` that only exports the stuff in `Language.Haskell.TH` that is needed for typed TH (namely the newtype `TExp` but not its constructor), plus perhaps the function `unTypeQ :: Q (TExp a) -> Q Exp` and additionally documents how to use typed TH splices and quotations. b) add a clear section to the manual that perhaps touches on some of this too? (its not clear if theres any real docs in the ghc manual on this :( ) -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/13003 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#13003: improve documentation for typed TH and make it more discoverable -------------------------------------+------------------------------------- Reporter: carter | Owner: Type: bug | Status: new Priority: normal | Milestone: 8.2.1 Component: Documentation | Version: 8.0.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 goldfire): The [https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts... #template-haskell section] on Template Haskell in the manual does describe the typed TH facility. Admittedly, this description is buried within the description for regular TH. A concrete suggestion for improvement (in other words, a patch) is very welcome. As for your suggestion (a), that might indeed be an improvement. Is this something that should go to the libraries@ mailing list? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/13003#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#13003: improve documentation for typed TH and make it more discoverable -------------------------------------+------------------------------------- Reporter: carter | Owner: Type: bug | Status: new Priority: normal | Milestone: 8.2.1 Component: Documentation | Version: 8.0.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 carter): I'm not sure if this really needs library list discussion. as for the docs, yeah, i'll see about a teeny patch that perhaps makes it a clear subsection? or something. not sure, but its definitely hidden there. Also its kinda an implementation detail/ quirk that they're under the same language flag too... it does make sense that theres some coercion functions between the underlying reps, but its quite odd that they're all under the same flag i think? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/13003#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#13003: improve documentation for typed TH and make it more discoverable -------------------------------------+------------------------------------- Reporter: carter | Owner: Type: bug | Status: new Priority: normal | Milestone: 8.2.1 Component: Documentation | Version: 8.0.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 goldfire): I think one could debate whether or not they should be under the same flag, but it's not clear to me that a new flag is needed. `-XTemplateHaskell` already enabled 4 different types of splices and quotes; typed TH just adds a fifth. In any case, I'm loath to break backward compatibility to fix this now. My suggestion about going via the mailing list is just to see what others think of this suggestion. Perhaps a list other than libraries@ is better. The problem is that I don't really trust my own instincts for this kind of user-facing design and would want to hear others weigh in. I'm not suggesting we go through an elaborate process -- I just want a few more voices. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/13003#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
participants (1)
-
GHC