Documentation fixes in 'template-haskell'

Summary:
 * Clarify the non-presence of derived classes in reified decls (#15167)
 * Clarify the shallowness of "reifyInstances" (#7066)
 * Mention that 'Typeable' instances are not found by reifyInstances (#11251)
 * Various Haddock markup issues fixed

Reviewers: goldfire, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, carter

GHC Trac Issues: #15167, #7066, #11251

Differential Revision: https://phabricator.haskell.org/D5197

2 files changed, 42 insertions, 25 deletions

diff --git a/libraries/template-haskell/Language/Haskell/TH/Quote.hs b/libraries/template-haskell/Language/Haskell/TH/Quote.hs
index 4ff5a2041b..d01d734e07 100644
--- a/libraries/template-haskell/Language/Haskell/TH/Quote.hs
+++ b/libraries/template-haskell/Language/Haskell/TH/Quote.hs
@@ -42,7 +42,7 @@ data QuasiQuoter = QuasiQuoter {
     }
 
 -- | 'quoteFile' takes a 'QuasiQuoter' and lifts it into one that read
--- the data out of a file.  For example, suppose 'asmq' is an 
+-- the data out of a file.  For example, suppose @asmq@ is an
 -- assembly-language quoter, so that you can write [asmq| ld r1, r2 |]
 -- as an expression. Then if you define @asmq_f = quoteFile asmq@, then
 -- the quote [asmq_f|foo.s|] will take input from file @"foo.s"@ instead
diff --git a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
index 294e443afb..7ee81c8d6e 100644
--- a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
+++ b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
@@ -377,6 +377,19 @@ reifyFixity nm = Q (qReifyFixity nm)
 if @nm@ is the name of a type class, then all instances of this class at the types @tys@
 are returned. Alternatively, if @nm@ is the name of a data family or type family,
 all instances of this family at the types @tys@ are returned.
+
+Note that this is a \"shallow\" test; the declarations returned merely have
+instance heads which unify with @nm tys@, they need not actually be satisfiable.
+
+  - @reifyInstances ''Eq [ 'TupleT' 2 \``AppT`\` 'ConT' ''A \``AppT`\` 'ConT' ''B ]@ contains
+    the @instance (Eq a, Eq b) => Eq (a, b)@ regardless of whether @A@ and
+    @B@ themselves implement 'Eq'
+
+  - @reifyInstances ''Show [ 'VarT' ('mkName' "a") ]@ produces every available
+    instance of 'Eq'
+
+There is one edge case: @reifyInstances ''Typeable tys@ currently always
+produces an empty list (no matter what @tys@ are given).
 -}
 reifyInstances :: Name -> [Type] -> Q [InstanceDec]
 reifyInstances cls tys = Q (qReifyInstances cls tys)
@@ -397,7 +410,7 @@ reifyAnnotations an = Q (qReifyAnnotations an)
 
 -- | @reifyModule mod@ looks up information about module @mod@.  To
 -- look up the current module, call this function with the return
--- value of @thisModule@.
+-- value of 'Language.Haskell.TH.Lib.thisModule'.
 reifyModule :: Module -> Q ModuleInfo
 reifyModule m = Q (qReifyModule m)
 
@@ -892,7 +905,7 @@ newtype ModName = ModName String        -- Module name
 newtype PkgName = PkgName String        -- package name
  deriving (Show,Eq,Ord,Data,Generic)
 
--- | Obtained from 'reifyModule' and 'thisModule'.
+-- | Obtained from 'reifyModule' and 'Language.Haskell.TH.Lib.thisModule'.
 data Module = Module PkgName ModName -- package qualified module name
  deriving (Show,Eq,Ord,Data,Generic)
 
@@ -1116,7 +1129,7 @@ Note that @mkName@ may be used with qualified names:
 > mkName "Prelude.pi"
 
 See also 'Language.Haskell.TH.Lib.dyn' for a useful combinator. The above example could
-be rewritten using 'dyn' as
+be rewritten using 'Language.Haskell.TH.Lib.dyn' as
 
 > f = [| pi + $(dyn "pi") |]
 -}
@@ -1344,7 +1357,10 @@ data Info
        Type
        ParentName
 
-  -- | A \"plain\" type constructor. \"Fancier\" type constructors are returned using 'PrimTyConI' or 'FamilyI' as appropriate
+  -- | A \"plain\" type constructor. \"Fancier\" type constructors are returned
+  -- using 'PrimTyConI' or 'FamilyI' as appropriate. At present, this reified
+  -- declaration will never have derived instances attached to it (if you wish
+  -- to check for an instance, see 'reifyInstances').
   | TyConI
         Dec
 
@@ -1354,7 +1370,8 @@ data Info
         Dec
         [InstanceDec]
 
-  -- | A \"primitive\" type constructor, which can't be expressed with a 'Dec'. Examples: @(->)@, @Int#@.
+  -- | A \"primitive\" type constructor, which can't be expressed with a 'Dec'.
+  -- Examples: @(->)@, @Int#@.
   | PrimTyConI
        Name
        Arity
@@ -1366,7 +1383,7 @@ data Info
        Type
        ParentName
 
-  -- | A pattern synonym.
+  -- | A pattern synonym
   | PatSynI
        Name
        PatSynType
@@ -1375,9 +1392,9 @@ data Info
   A \"value\" variable (as opposed to a type variable, see 'TyVarI').
 
   The @Maybe Dec@ field contains @Just@ the declaration which
-  defined the variable -- including the RHS of the declaration --
+  defined the variable - including the RHS of the declaration -
   or else @Nothing@, in the case where the RHS is unavailable to
-  the compiler. At present, this value is _always_ @Nothing@:
+  the compiler. At present, this value is /always/ @Nothing@:
   returning the RHS has not yet been implemented because of
   lack of interest.
   -}
@@ -1761,51 +1778,51 @@ data DerivStrategy = StockStrategy    -- ^ A \"standard\" derived instance
                    | ViaStrategy Type -- ^ @-XDerivingVia@
   deriving( Show, Eq, Ord, Data, Generic )
 
--- | A Pattern synonym's type. Note that a pattern synonym's *fully*
+-- | A pattern synonym's type. Note that a pattern synonym's /fully/
 -- specified type has a peculiar shape coming with two forall
 -- quantifiers and two constraint contexts. For example, consider the
 -- pattern synonym
 --
---   pattern P x1 x2 ... xn = <some-pattern>
+-- > pattern P x1 x2 ... xn = <some-pattern>
 --
 -- P's complete type is of the following form
 --
---   forall universals. required constraints
---     => forall existentials. provided constraints
---     => t1 -> t2 -> ... -> tn -> t
+-- > pattern P :: forall universals.   required constraints
+-- >           => forall existentials. provided constraints
+-- >           => t1 -> t2 -> ... -> tn -> t
 --
 -- consisting of four parts:
 --
---   1) the (possibly empty lists of) universally quantified type
+--   1. the (possibly empty lists of) universally quantified type
 --      variables and required constraints on them.
---   2) the (possibly empty lists of) existentially quantified
+--   2. the (possibly empty lists of) existentially quantified
 --      type variables and the provided constraints on them.
---   3) the types t1, t2, .., tn of x1, x2, .., xn, respectively
---   4) the type t of <some-pattern>, mentioning only universals.
+--   3. the types @t1@, @t2@, .., @tn@ of @x1@, @x2@, .., @xn@, respectively
+--   4. the type @t@ of @\<some-pattern\>@, mentioning only universals.
 --
 -- Pattern synonym types interact with TH when (a) reifying a pattern
 -- synonym, (b) pretty printing, or (c) specifying a pattern synonym's
 -- type signature explicitly:
 --
--- (a) Reification always returns a pattern synonym's *fully* specified
+--   * Reification always returns a pattern synonym's /fully/ specified
 --     type in abstract syntax.
 --
--- (b) Pretty printing via 'pprPatSynType' abbreviates a pattern
---     synonym's type unambiguously in concrete syntax: The rule of
+--   * Pretty printing via 'Language.Haskell.TH.Ppr.pprPatSynType' abbreviates
+--     a pattern synonym's type unambiguously in concrete syntax: The rule of
 --     thumb is to print initial empty universals and the required
---     context as `() =>`, if existentials and a provided context
+--     context as @() =>@, if existentials and a provided context
 --     follow. If only universals and their required context, but no
 --     existentials are specified, only the universals and their
 --     required context are printed. If both or none are specified, so
 --     both (or none) are printed.
 --
--- (c) When specifying a pattern synonym's type explicitly with
+--   * When specifying a pattern synonym's type explicitly with
 --     'PatSynSigD' either one of the universals, the existentials, or
 --     their contexts may be left empty.
 --
 -- See the GHC user's guide for more information on pattern synonyms
--- and their types: https://downloads.haskell.org/~ghc/latest/docs/html/
--- users_guide/syntax-extns.html#pattern-synonyms.
+-- and their types:
+-- <https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#pattern-synonyms>.
 type PatSynType = Type
 
 -- | Common elements of 'OpenTypeFamilyD' and 'ClosedTypeFamilyD'. By