[Git][ghc/ghc][master] Update haddocks of Import/Export AST types
Marge Bot (@marge-bot)
gitlab at gitlab.haskell.org
Thu Jun 20 11:24:49 UTC 2024
Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC
Commits:
5e8faaf1 by Jan Hrček at 2024-06-20T07:23:20-04:00
Update haddocks of Import/Export AST types
- - - - -
11 changed files:
- compiler/GHC/Core/DataCon.hs
- compiler/GHC/Hs/Binds.hs
- compiler/GHC/Hs/Extension.hs
- compiler/GHC/Hs/ImpExp.hs
- compiler/GHC/Parser/Lexer.x
- compiler/GHC/Parser/PostProcess.hs
- compiler/GHC/ThToHs.hs
- compiler/GHC/Types/Basic.hs
- compiler/GHC/Types/ForeignCall.hs
- compiler/Language/Haskell/Syntax/Expr.hs
- compiler/Language/Haskell/Syntax/ImpExp.hs
Changes:
=====================================
compiler/GHC/Core/DataCon.hs
=====================================
@@ -849,7 +849,7 @@ type DataConEnv a = UniqFM DataCon a -- Keyed by DataCon
-- emit a warning (in checkValidDataCon) and treat it like
-- @(HsSrcBang _ NoSrcUnpack SrcLazy)@
data HsSrcBang =
- HsSrcBang SourceText -- Note [Pragma source text] in "GHC.Types.SourceText"
+ HsSrcBang SourceText -- See Note [Pragma source text] in "GHC.Types.SourceText"
SrcUnpackedness
SrcStrictness
deriving Data.Data
=====================================
compiler/GHC/Hs/Binds.hs
=====================================
@@ -714,7 +714,7 @@ type instance XSpecInstSig (GhcPass p) = ([AddEpAnn], SourceText)
type instance XMinimalSig (GhcPass p) = ([AddEpAnn], SourceText)
type instance XSCCFunSig (GhcPass p) = ([AddEpAnn], SourceText)
type instance XCompleteMatchSig (GhcPass p) = ([AddEpAnn], SourceText)
- -- SourceText: Note [Pragma source text] in "GHC.Types.SourceText"
+ -- SourceText: See Note [Pragma source text] in "GHC.Types.SourceText"
type instance XXSig GhcPs = DataConCantHappen
type instance XXSig GhcRn = IdSig
type instance XXSig GhcTc = IdSig
=====================================
compiler/GHC/Hs/Extension.hs
=====================================
@@ -172,11 +172,15 @@ type GhcTc = GhcPass 'Typechecked -- Output of typechecker
-- | Allows us to check what phase we're in at GHC's runtime.
-- For example, this class allows us to write
--- > f :: forall p. IsPass p => HsExpr (GhcPass p) -> blah
--- > f e = case ghcPass @p of
--- > GhcPs -> ... in this RHS we have HsExpr GhcPs...
--- > GhcRn -> ... in this RHS we have HsExpr GhcRn...
--- > GhcTc -> ... in this RHS we have HsExpr GhcTc...
+--
+-- @
+-- f :: forall p. IsPass p => HsExpr (GhcPass p) -> blah
+-- f e = case ghcPass @p of
+-- GhcPs -> ... in this RHS we have HsExpr GhcPs...
+-- GhcRn -> ... in this RHS we have HsExpr GhcRn...
+-- GhcTc -> ... in this RHS we have HsExpr GhcTc...
+-- @
+--
-- which is very useful, for example, when pretty-printing.
-- See Note [IsPass].
class ( NoGhcTcPass (NoGhcTcPass p) ~ NoGhcTcPass p
=====================================
compiler/GHC/Hs/ImpExp.hs
=====================================
@@ -81,11 +81,10 @@ type instance ImportDeclPkgQual GhcTc = PkgQual
type instance XCImportDecl GhcPs = XImportDeclPass
type instance XCImportDecl GhcRn = XImportDeclPass
type instance XCImportDecl GhcTc = DataConCantHappen
- -- Note [Pragma source text] in "GHC.Types.SourceText"
data XImportDeclPass = XImportDeclPass
{ ideclAnn :: EpAnn EpAnnImportDecl
- , ideclSourceText :: SourceText
+ , ideclSourceText :: SourceText -- Note [Pragma source text] in "GHC.Types.SourceText"
, ideclImplicit :: Bool
-- ^ GHC generates an `ImportDecl` to represent the invisible `import Prelude`
-- that appears in any file that omits `import Prelude`, setting
@@ -112,12 +111,12 @@ deriving instance Eq (IEWrappedName GhcTc)
-- API Annotations types
data EpAnnImportDecl = EpAnnImportDecl
- { importDeclAnnImport :: EpaLocation
- , importDeclAnnPragma :: Maybe (EpaLocation, EpaLocation)
- , importDeclAnnSafe :: Maybe EpaLocation
- , importDeclAnnQualified :: Maybe EpaLocation
- , importDeclAnnPackage :: Maybe EpaLocation
- , importDeclAnnAs :: Maybe EpaLocation
+ { importDeclAnnImport :: EpaLocation -- ^ The location of the @import@ keyword
+ , importDeclAnnPragma :: Maybe (EpaLocation, EpaLocation) -- ^ The locations of @{-# SOURCE@ and @#-}@ respectively
+ , importDeclAnnSafe :: Maybe EpaLocation -- ^ The location of the @safe@ keyword
+ , importDeclAnnQualified :: Maybe EpaLocation -- ^ The location of the @qualified@ keyword
+ , importDeclAnnPackage :: Maybe EpaLocation -- ^ The location of the package name (when using @-XPackageImports@)
+ , importDeclAnnAs :: Maybe EpaLocation -- ^ The location of the @as@ keyword
} deriving (Data)
instance NoAnn EpAnnImportDecl where
=====================================
compiler/GHC/Parser/Lexer.x
=====================================
@@ -863,7 +863,7 @@ data Token
| ITdependency
| ITrequires
- -- Pragmas, see Note [Pragma source text] in "GHC.Types.SourceText"
+ -- Pragmas, see Note [Pragma source text] in "GHC.Types.SourceText"
| ITinline_prag SourceText InlineSpec RuleMatchInfo
| ITopaque_prag SourceText
| ITspec_prag SourceText -- SPECIALISE
=====================================
compiler/GHC/Parser/PostProcess.hs
=====================================
@@ -2721,7 +2721,7 @@ mkInlinePragma :: SourceText -> (InlineSpec, RuleMatchInfo) -> Maybe Activation
-- The (Maybe Activation) is because the user can omit
-- the activation spec (and usually does)
mkInlinePragma src (inl, match_info) mb_act
- = InlinePragma { inl_src = src -- Note [Pragma source text] in "GHC.Types.SourceText"
+ = InlinePragma { inl_src = src -- See Note [Pragma source text] in "GHC.Types.SourceText"
, inl_inline = inl
, inl_sat = Nothing
, inl_act = act
=====================================
compiler/GHC/ThToHs.hs
=====================================
@@ -1883,7 +1883,7 @@ In the process, all parens are stripped out, as they are not needed.
This Convert module then converts the TH AST back to hsSyn AST.
-In order to pretty-print this hsSyn AST, parens need to be adde back at certain
+In order to pretty-print this hsSyn AST, parens need to be added back at certain
points so that the code is readable with its original meaning.
So scattered through "GHC.ThToHs" are various points where parens are added.
=====================================
compiler/GHC/Types/Basic.hs
=====================================
@@ -1571,7 +1571,7 @@ no harm.
data InlinePragma -- Note [InlinePragma]
= InlinePragma
- { inl_src :: SourceText -- Note [Pragma source text]
+ { inl_src :: SourceText -- See Note [Pragma source text]
, inl_inline :: InlineSpec -- See Note [inl_inline and inl_act]
, inl_sat :: Maybe Arity -- Just n <=> Inline only when applied to n
=====================================
compiler/GHC/Types/ForeignCall.hs
=====================================
@@ -222,7 +222,7 @@ instance Outputable CCallSpec where
= text "__ffi_dyn_ccall" <> gc_suf <+> text "\"\""
-- The filename for a C header file
--- Note [Pragma source text] in "GHC.Types.SourceText"
+-- See Note [Pragma source text] in "GHC.Types.SourceText"
data Header = Header SourceText FastString
deriving (Eq, Data)
@@ -236,7 +236,7 @@ instance Outputable Header where
-- 'GHC.Parser.Annotation.AnnClose' @'\#-}'@,
-- For details on above see Note [exact print annotations] in "GHC.Parser.Annotation"
-data CType = CType SourceText -- Note [Pragma source text] in "GHC.Types.SourceText"
+data CType = CType SourceText -- See Note [Pragma source text] in "GHC.Types.SourceText"
(Maybe Header) -- header to include for this type
(SourceText,FastString) -- the type itself
deriving (Eq, Data)
=====================================
compiler/Language/Haskell/Syntax/Expr.hs
=====================================
@@ -285,7 +285,8 @@ data HsExpr p
| HsOverLabel (XOverLabel p) SourceText FastString
-- ^ Overloaded label (Note [Overloaded labels] in GHC.OverloadedLabels)
- -- Note [Pragma source text] in GHC.Types.SourceText
+
+ -- See Note [Pragma source text] in "GHC.Types.SourceText"
| HsIPVar (XIPVar p)
HsIPName -- ^ Implicit parameter (not in use after typechecking)
=====================================
compiler/Language/Haskell/Syntax/ImpExp.hs
=====================================
@@ -30,11 +30,6 @@ One per import declaration in a module.
-- | Located Import Declaration
type LImportDecl pass = XRec pass (ImportDecl pass)
- -- ^ When in a list this may have
- --
- -- - 'GHC.Parser.Annotation.AnnKeywordId' : 'GHC.Parser.Annotation.AnnSemi'
-
- -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
-- | If/how an import is 'qualified'.
data ImportDeclQualifiedStyle
@@ -58,10 +53,10 @@ instance NFData IsBootInterface where
-- A single Haskell @import@ declaration.
data ImportDecl pass
= ImportDecl {
- ideclExt :: XCImportDecl pass,
+ ideclExt :: XCImportDecl pass, -- ^ Locations of keywords like @import@, @qualified@, etc. are captured here.
ideclName :: XRec pass ModuleName, -- ^ Module name.
ideclPkgQual :: ImportDeclPkgQual pass, -- ^ Package qualifier.
- ideclSource :: IsBootInterface, -- ^ IsBoot <=> {-\# SOURCE \#-} import
+ ideclSource :: IsBootInterface, -- ^ IsBoot \<=> {-\# SOURCE \#-} import
ideclSafe :: Bool, -- ^ True => safe import
ideclQualified :: ImportDeclQualifiedStyle, -- ^ If/how the import is qualified.
ideclAs :: Maybe (XRec pass ModuleName), -- ^ as Module
@@ -69,24 +64,8 @@ data ImportDecl pass
-- ^ Explicit import list (EverythingBut => hiding, names)
}
| XImportDecl !(XXImportDecl pass)
- -- ^
- -- 'GHC.Parser.Annotation.AnnKeywordId's
- --
- -- - 'GHC.Parser.Annotation.AnnImport'
- --
- -- - 'GHC.Parser.Annotation.AnnOpen', 'GHC.Parser.Annotation.AnnClose' for ideclSource
- --
- -- - 'GHC.Parser.Annotation.AnnSafe','GHC.Parser.Annotation.AnnQualified',
- -- 'GHC.Parser.Annotation.AnnPackageName','GHC.Parser.Annotation.AnnAs',
- -- 'GHC.Parser.Annotation.AnnVal'
- --
- -- - 'GHC.Parser.Annotation.AnnHiding','GHC.Parser.Annotation.AnnOpen',
- -- 'GHC.Parser.Annotation.AnnClose' attached
- -- to location in ideclImportList
-
- -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
-
--- | Whether the import list is exactly what to import, or whether `hiding` was
+
+-- | Whether the import list is exactly what to import, or whether @hiding@ was
-- used, and therefore everything but what was listed should be imported
data ImportListInterpretation = Exactly | EverythingBut
deriving (Eq, Data)
@@ -107,7 +86,7 @@ type ExportDoc pass = LHsDoc pass
-- | Imported or exported entity.
data IE pass
- = IEVar (XIEVar pass) (LIEWrappedName pass) (Maybe (ExportDoc pass))
+ = IEVar (XIEVar pass) (LIEWrappedName pass) (Maybe (ExportDoc pass))
-- ^ Imported or exported variable
--
-- @
@@ -115,36 +94,34 @@ data IE pass
-- import Mod ( test )
-- @
- | IEThingAbs (XIEThingAbs pass) (LIEWrappedName pass) (Maybe (ExportDoc pass))
+ | IEThingAbs (XIEThingAbs pass) (LIEWrappedName pass) (Maybe (ExportDoc pass))
-- ^ Imported or exported Thing with absent subordinate list
--
- -- The thing is a typeclass or type (can't tell)
- -- - 'GHC.Parser.Annotation.AnnKeywordId's : 'GHC.Parser.Annotation.AnnPattern',
- -- 'GHC.Parser.Annotation.AnnType','GHC.Parser.Annotation.AnnVal'
+ -- The thing is a Class\/Type (can't tell)
--
-- @
-- module Mod ( Test )
-- import Mod ( Test )
-- @
- -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
-- See Note [Located RdrNames] in GHC.Hs.Expr
| IEThingAll (XIEThingAll pass) (LIEWrappedName pass) (Maybe (ExportDoc pass))
- -- ^ Imported or exported thing with wildcard subordinate list (e..g @(..)@)
+ -- ^ Imported or exported thing with wildcard subordinate list (e.g. @(..)@)
--
- -- The thing is a Class/Type and the All refers to methods/constructors
+ -- The thing is a Class\/Type and the All refers to methods\/constructors
--
- -- - 'GHC.Parser.Annotation.AnnKeywordId's : 'GHC.Parser.Annotation.AnnOpen',
- -- 'GHC.Parser.Annotation.AnnDotdot','GHC.Parser.Annotation.AnnClose',
- -- 'GHC.Parser.Annotation.AnnType'
-- @
-- module Mod ( Test(..) )
-- import Mod ( Test(..) )
-- @
+ --
+ -- exactprint: the location of parens and @..@ is captured via 'GHC.Parser.Annotation.AnnKeywordId's :
+ -- 'GHC.Parser.Annotation.AnnOpenP',
+ -- 'GHC.Parser.Annotation.AnnDotdot',
+ -- 'GHC.Parser.Annotation.AnnCloseP'
-- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
-- See Note [Located RdrNames] in GHC.Hs.Expr
-
| IEThingWith (XIEThingWith pass)
(LIEWrappedName pass)
IEWildcard
@@ -152,31 +129,30 @@ data IE pass
(Maybe (ExportDoc pass))
-- ^ Imported or exported thing with explicit subordinate list.
--
- -- The thing is a Class/Type and the imported or exported things are
+ -- The thing is a Class\/Type (can't tell) and the imported or exported things are
-- its children.
- -- - 'GHC.Parser.Annotation.AnnKeywordId's : 'GHC.Parser.Annotation.AnnOpen',
- -- 'GHC.Parser.Annotation.AnnClose',
- -- 'GHC.Parser.Annotation.AnnComma',
- -- 'GHC.Parser.Annotation.AnnType'
+ --
-- @
- -- module Mod ( Test(..) )
- -- import Mod ( Test(..) )
+ -- module Mod ( Test(f, g) )
+ -- import Mod ( Test(f, g) )
-- @
+ --
+ -- exactprint: the location of parens is captured via 'GHC.Parser.Annotation.AnnKeywordId's :
+ -- 'GHC.Parser.Annotation.AnnOpenP', 'GHC.Parser.Annotation.AnnCloseP'
-- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
| IEModuleContents (XIEModuleContents pass) (XRec pass ModuleName)
- -- ^ Imported or exported module contents
- --
- -- (Export Only)
- --
- -- - 'GHC.Parser.Annotation.AnnKeywordId's : 'GHC.Parser.Annotation.AnnModule'
+ -- ^ Export of entire module. Can only occur in export list.
--
-- @
-- module Mod ( module Mod2 )
-- @
+ --
+ -- exactprint: the location of @module@ keyword is capture via 'GHC.Parser.Annotation.AnnKeywordId' :
+ -- 'GHC.Parser.Annotation.AnnModule'
-- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
- | IEGroup (XIEGroup pass) Int (LHsDoc pass) -- ^ Doc section heading
+ | IEGroup (XIEGroup pass) Int (LHsDoc pass)
-- ^ A Haddock section in an export list.
--
-- @
@@ -185,7 +161,7 @@ data IE pass
-- ...
-- )
-- @
- | IEDoc (XIEDoc pass) (LHsDoc pass) -- ^ Some documentation
+ | IEDoc (XIEDoc pass) (LHsDoc pass)
-- ^ A bit of unnamed documentation.
--
-- @
@@ -194,7 +170,7 @@ data IE pass
-- ...
-- )
-- @
- | IEDocNamed (XIEDocNamed pass) String -- ^ Reference to named doc
+ | IEDocNamed (XIEDocNamed pass) String
-- ^ A reference to a named documentation chunk.
--
-- @
@@ -216,17 +192,16 @@ data IEWildcard
-- | A name in an import or export specification which may have
-- adornments. Used primarily for accurate pretty printing of
--- ParsedSource, and API Annotation placement. The
--- 'GHC.Parser.Annotation' is the location of the adornment in
--- the original source.
+-- ParsedSource, and API Annotation placement.
data IEWrappedName p
- = IEName (XIEName p) (LIdP p) -- ^ no extra
- | IEPattern (XIEPattern p) (LIdP p) -- ^ pattern X
- | IEType (XIEType p) (LIdP p) -- ^ type (:+:)
+ = IEName (XIEName p) (LIdP p) -- ^ unadorned name, e.g @myFun@
+ | IEPattern (XIEPattern p) (LIdP p) -- ^ @pattern X@
+ --
+ -- exactprint: the location of @pattern@ keyword is captured via 'GHC.Parser.Annotation.EpaLocation'
+ | IEType (XIEType p) (LIdP p) -- ^ @type (:+:)@
+ --
+ -- exactprint: the location of @type@ keyword is captured via 'GHC.Parser.Annotation.EpaLocation'
| XIEWrappedName !(XXIEWrappedName p)
-- | Located name with possible adornment
--- - 'GHC.Parser.Annotation.AnnKeywordId's : 'GHC.Parser.Annotation.AnnType',
--- 'GHC.Parser.Annotation.AnnPattern'
type LIEWrappedName p = XRec p (IEWrappedName p)
--- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/5e8faaf143d50c4ac88dafb7e440e85fbcedf1fc
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/5e8faaf143d50c4ac88dafb7e440e85fbcedf1fc
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/20240620/5ab056ff/attachment-0001.html>
More information about the ghc-commits
mailing list