[Git][ghc/ghc][wip/T18462] Add documentation
Sjoerd Visscher (@trac-sjoerd_visscher)
gitlab at gitlab.haskell.org
Thu Jan 23 11:29:56 UTC 2025
Sjoerd Visscher pushed to branch wip/T18462 at Glasgow Haskell Compiler / GHC
Commits:
be8b6857 by Sjoerd Visscher at 2025-01-23T12:29:47+01:00
Add documentation
- - - - -
5 changed files:
- compiler/GHC/Core/Rules.hs
- compiler/GHC/Hs/Type.hs
- compiler/GHC/Tc/Solver/Solve.hs
- compiler/Language/Haskell/Syntax/Type.hs
- libraries/ghc-internal/src/GHC/Internal/TypeError.hs
Changes:
=====================================
compiler/GHC/Core/Rules.hs
=====================================
@@ -1282,7 +1282,7 @@ Two wrinkles:
f (\(MkT @b (d::Num b) (x::b)) -> h @b d x) = ...
where the HOP is (h @b d x). In principle this might be possible, but
it seems fragile; e.g. we would still need to insist that the (invisible)
- @b was a type variable. And since `h` gets a polymoprhic type, that
+ @b was a type variable. And since `h` gets a polymorphic type, that
type would have to be declared by the programmer.
Maybe one day. But for now, we insist (in `arg_as_lcl_var`)that a HOP
=====================================
compiler/GHC/Hs/Type.hs
=====================================
@@ -488,6 +488,11 @@ type instance XXType GhcPs = HsTypeGhcPsExt GhcPs
type instance XXType GhcRn = HsCoreTy
type instance XXType GhcTc = DataConCantHappen
+type instance XNumTy (GhcPass _) = SourceText
+type instance XStrTy (GhcPass _) = SourceText
+type instance XCharTy (GhcPass _) = SourceText
+type instance XXTyLit (GhcPass _) = DataConCantHappen
+
-- An escape hatch for tunnelling a Core 'Type' through 'HsType'.
-- For more details on how this works, see:
--
@@ -496,19 +501,27 @@ type instance XXType GhcTc = DataConCantHappen
-- * @Note [Typechecking HsCoreTys]@ in "GHC.Tc.Gen.HsType"
type HsCoreTy = Type
-type instance XNumTy (GhcPass _) = SourceText
-type instance XStrTy (GhcPass _) = SourceText
-type instance XCharTy (GhcPass _) = SourceText
-type instance XXTyLit (GhcPass _) = DataConCantHappen
-
data HsTypeGhcPsExt pass
= HsCoreTy HsCoreTy
| HsBangTy (XBangTy pass) -- Contains the SourceText in GHC passes.
- HsBang (LHsType pass) -- Bang-style type annotations
+ HsBang (LHsType pass) -- See Note [Parsing data type declarations]
| HsRecTy (XRecTy pass)
- [LConDeclField pass] -- Only in data type declarations
+ [LConDeclField pass] -- See Note [Parsing data type declarations]
+
+{- Note [Parsing data type declarations]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When parsing it is not always clear if we're parsing a constructor field type
+or not. So during parsing we extend the type syntax to support bang annotations
+and record braces. Once parsing is done these extensions are removed and
+the data is stored in the HsConFieldSpec. It is an error if it turns out
+the extensions were used outside of a constructor field type.
+
+Conversely it is convenient to have these extensions when generating
+documentation with Haddock. So in Haddock the type syntax is extended again
+from the data in HsConFieldSpec.
+-}
data EpLinearArrow
= EpPct1 !(EpToken "%1") !(TokRarrow)
@@ -548,6 +561,7 @@ multAnnToHsType = expandHsMultAnnOn (HsTyVar noAnn NotPromoted)
-- | Convert an multiplicity annotation into its corresponding multiplicity.
-- In essence this erases the information of whether the programmer wrote an explicit
-- multiplicity or a shorthand.
+-- In this polymorphic function, `t` can be `HsType` or `HsExpr`
expandHsMultAnnOn :: (LocatedN Name -> t GhcRn) -> HsMultAnnOn on (LocatedA (t GhcRn)) GhcRn -> LocatedA (t GhcRn)
expandHsMultAnnOn mk_var (HsUnannotated HsUnannOne _) = noLocA (mk_var (noLocA oneDataConName))
expandHsMultAnnOn mk_var (HsUnannotated HsUnannMany _) = noLocA (mk_var (noLocA manyDataConName))
=====================================
compiler/GHC/Tc/Solver/Solve.hs
=====================================
@@ -851,7 +851,7 @@ everything to be in terms of b, while k does none of that. This is
ridiculous, but I (Richard E) don't see a good fix.
Shortcoming 2. Removing a redundant constraint can cause clients to fail to
-compile, by making the function more polymoprhic. Consider (#16154)
+compile, by making the function more polymorphic. Consider (#16154)
f :: (a ~ Bool) => a -> Int
f x = 3
=====================================
compiler/Language/Haskell/Syntax/Type.hs
=====================================
@@ -1084,6 +1084,24 @@ data ConDeclField pass
cd_fld_spec :: HsConFieldSpec OnRecField pass }
| XConDeclField !(XXConDeclField pass)
+{- Note [ConDeclField pass]
+~~~~~~~~~~~~~~~~~~~~~~~~~
+A ConDeclField contains a list of field occurrences: these always
+include the field label as the user wrote it. After the renamer, it
+will additionally contain the identity of the selector function in the
+second component.
+
+Due to DuplicateRecordFields, the OccName of the selector function
+may have been mangled, which is why we keep the original field label
+separately. For example, when DuplicateRecordFields is enabled
+
+ data T = MkT { x :: Int }
+
+gives
+
+ ConDeclField { cd_fld_names = [L _ (FieldOcc "x" $sel:x:MkT)], ... }.
+-}
+
-- | Describes the arguments to a data constructor. This is a common
-- representation for several constructor-related concepts, including:
--
@@ -1111,35 +1129,51 @@ data HsConDetails tyarg arg rec
noTypeArgs :: [Void]
noTypeArgs = []
+-- | Constructor field specification, see Note [HsConFieldSpec on pass]
data HsConFieldSpec on pass
= CFS { cfs_ext :: XConFieldSpec pass
+ -- ^ Extension point
+
, cfs_unpack :: SrcUnpackedness
+ -- ^ UNPACK pragma if any
+ -- E.g. data T = MkT {-# UNPACK #-} Int
+
, cfs_bang :: SrcStrictness
+ -- ^ User-specified strictness, if any
+ -- E.g. data T a = MkT !a
+
, cfs_multiplicity :: HsMultAnnOn on (LHsType pass) pass
+ -- ^ User-specified multiplicity, if any
+ -- E.g. data T a = MkT { t %Many :: a }
+ -- or data T a where MtT :: a %1 -> T a
+
, cfs_type :: LHsType pass
- , cfs_doc :: Maybe (LHsDoc pass) }
+ -- ^ The type of the field
+
+ , cfs_doc :: Maybe (LHsDoc pass)
+ -- ^ Documentation for the field
+ -- F.e. this very piece of documentation
+ }
hsConFieldSpecGeneralize :: HsConFieldSpec on pass -> HsConFieldSpec on1 pass
hsConFieldSpecGeneralize = unsafeCoerce
-{-
-Note [ConDeclField pass]
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A ConDeclField contains a list of field occurrences: these always
-include the field label as the user wrote it. After the renamer, it
-will additionally contain the identity of the selector function in the
-second component.
-
-Due to DuplicateRecordFields, the OccName of the selector function
-may have been mangled, which is why we keep the original field label
-separately. For example, when DuplicateRecordFields is enabled
-
- data T = MkT { x :: Int }
-
-gives
-
- ConDeclField { cd_fld_names = [L _ (FieldOcc "x" $sel:x:MkT)], ... }.
+{- Note [HsConFieldSpec on pass]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`HsConFieldSpec` is used to specify the type of a data single constructor argument for all of:
+* Haskell-98 style declarations (with prefix, infix or record syntax)
+ e.g. data T1 a = MkT (Maybe a) !Int
+* GADT-style declarations with arrow syntax
+ e.g. data T2 a where MkT :: Maybe a -> !Int -> T2 a
+* GADT-style declarations with record syntax
+ e.g. data T3 a where MkT :: { x :: Maybe a, y :: !Int } -> T3 a
+
+These argument types are decorated with any user-defined
+ a) UNPACK pragma `cfs_unpack`
+ b) strictness annotation `cfs_bang`
+ c) multiplicity annotation `cfs_multiplicity`
+ In the case of Haskell-98 style declarations, this only applies to record syntax.
+ d) documentation `cfs_doc`
-}
-----------------------
=====================================
libraries/ghc-internal/src/GHC/Internal/TypeError.hs
=====================================
@@ -162,7 +162,7 @@ Note [The Unsatisfiable representation-polymorphism trick]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The class method `unsatisfiableLifted :: forall (a::Type). Unsatisfiable msg => a`
works only for lifted types `a`. What if we want an unsatisfiable value of type
-`Int#`, say? The function `unsatisfiable` has a representation-polymoprhic type
+`Int#`, say? The function `unsatisfiable` has a representation-polymorphic type
unsatisfiable :: forall {rep} (msg :: ErrorMessage) (b :: TYPE rep).
Unsatisfiable msg => b
and yet is defined in terms of `unsatisfiableLifted`. How? By instantiating
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/be8b685781e859303aebc6572398ab5b8187543a
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/be8b685781e859303aebc6572398ab5b8187543a
You're receiving this email because of your account on gitlab.haskell.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20250123/59153de8/attachment-0001.html>
More information about the ghc-commits
mailing list