GHC.Hs.Doc

ghc-lib-parser-9.14.1.20251220: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Hs.Doc

Description

Types and functions for raw and lexed docstrings.

Synopsis

- type HsDoc = WithHsDocIdentifiers HsDocString
- data WithHsDocIdentifiers a pass = WithHsDocIdentifiers {
  - hsDocString :: !a
  - hsDocIdentifiers :: ![Located (IdP pass)]
  }
- hsDocIds :: WithHsDocIdentifiers a GhcRn -> NameSet
- type LHsDoc pass = Located (HsDoc pass)
- pprHsDocDebug :: Outputable (IdP name) => HsDoc name -> SDoc
- pprWithDoc :: LHsDoc name -> SDoc -> SDoc
- pprMaybeWithDoc :: Maybe (LHsDoc name) -> SDoc -> SDoc
- module GHC.Hs.DocString
- data ExtractedTHDocs = ExtractedTHDocs {
  - ethd_mod_header :: Maybe (HsDoc GhcRn)
  - ethd_decl_docs :: UniqMap Name (HsDoc GhcRn)
  - ethd_arg_docs :: UniqMap Name (IntMap (HsDoc GhcRn))
  - ethd_inst_docs :: UniqMap Name (HsDoc GhcRn)
  }
- data DocStructureItem
  - = DsiSectionHeading !Int !(HsDoc GhcRn)
  - | DsiDocChunk !(HsDoc GhcRn)
  - | DsiNamedChunkRef !String
  - | DsiExports !DetOrdAvails
  - | DsiModExport !(NonEmpty ModuleName) !DetOrdAvails
- type DocStructure = [DocStructureItem]
- data Docs = Docs {
  - docs_mod_hdr :: Maybe (HsDoc GhcRn)
  - docs_exports :: UniqMap Name (HsDoc GhcRn)
  - docs_decls :: UniqMap Name [HsDoc GhcRn]
  - docs_args :: UniqMap Name (IntMap (HsDoc GhcRn))
  - docs_structure :: DocStructure
  - docs_named_chunks :: Map String (HsDoc GhcRn)
  - docs_haddock_opts :: Maybe String
  - docs_language :: Maybe Language
  - docs_extensions :: EnumSet Extension
  }
- emptyDocs :: Docs

# Documentation

type HsDoc = WithHsDocIdentifiers HsDocString #

A docstring with the (probable) identifiers found in it.

data WithHsDocIdentifiers a pass #

Annotate a value with the probable identifiers found in it These will be used by haddock to generate links.

The identifiers are bundled along with their location in the source file. This is useful for tooling to know exactly where they originate.

This type is currently used in two places - for regular documentation comments, with `a` set to `HsDocString`, and for adding identifier information to warnings, where `a` is `StringLiteral`

Constructors

WithHsDocIdentifiers |
Fields hsDocString :: !a hsDocIdentifiers :: ![Located (IdP pass)]

#### Instances

Instances details

(NFData (IdP pass), NFData a) => NFData (WithHsDocIdentifiers a pass) # |
Instance details Defined in GHC.Hs.Doc Methods rnf :: WithHsDocIdentifiers a pass -> () #
(Data pass, Data (IdP pass), Data a) => Data (WithHsDocIdentifiers a pass) # |
Instance details Defined in GHC.Hs.Doc Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> WithHsDocIdentifiers a pass -> c (WithHsDocIdentifiers a pass) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (WithHsDocIdentifiers a pass) # toConstr :: WithHsDocIdentifiers a pass -> Constr # dataTypeOf :: WithHsDocIdentifiers a pass -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (WithHsDocIdentifiers a pass)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (WithHsDocIdentifiers a pass)) # gmapT :: (forall b. Data b => b -> b) -> WithHsDocIdentifiers a pass -> WithHsDocIdentifiers a pass # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> WithHsDocIdentifiers a pass -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> WithHsDocIdentifiers a pass -> r # gmapQ :: (forall d. Data d => d -> u) -> WithHsDocIdentifiers a pass -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> WithHsDocIdentifiers a pass -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> WithHsDocIdentifiers a pass -> m (WithHsDocIdentifiers a pass) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> WithHsDocIdentifiers a pass -> m (WithHsDocIdentifiers a pass) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> WithHsDocIdentifiers a pass -> m (WithHsDocIdentifiers a pass) #
Binary a => Binary (WithHsDocIdentifiers a GhcRn) # |
Instance details Defined in GHC.Hs.Doc Methods put_ :: WriteBinHandle -> WithHsDocIdentifiers a GhcRn -> IO () # put :: WriteBinHandle -> WithHsDocIdentifiers a GhcRn -> IO (Bin (WithHsDocIdentifiers a GhcRn)) # get :: ReadBinHandle -> IO (WithHsDocIdentifiers a GhcRn) #
Outputable a => Outputable (WithHsDocIdentifiers a pass) # | For compatibility with the existing @-ddump-parsed' output, we only show the docstring. Use `pprHsDoc` to show `HsDoc`'s internals.
Instance details Defined in GHC.Hs.Doc Methods ppr :: WithHsDocIdentifiers a pass -> SDoc #
(Eq (IdP pass), Eq a) => Eq (WithHsDocIdentifiers a pass) # |
Instance details Defined in GHC.Hs.Doc Methods (==) :: WithHsDocIdentifiers a pass -> WithHsDocIdentifiers a pass -> Bool # (/=) :: WithHsDocIdentifiers a pass -> WithHsDocIdentifiers a pass -> Bool #

hsDocIds :: WithHsDocIdentifiers a GhcRn -> NameSet #

Extract a mapping from the lexed identifiers to the names they may correspond to.

type LHsDoc pass = Located (HsDoc pass) #

pprHsDocDebug :: Outputable (IdP name) => HsDoc name -> SDoc #

Print a doc with its identifiers, useful for debugging

pprWithDoc :: LHsDoc name -> SDoc -> SDoc #

Pretty print a thing with its doc The docstring will include the comment decorators '-- |', '{-|' etc and will come either before or after depending on how it was written i.e it will come after the thing if it is a '-- ^' or '{-^' and before otherwise.

pprMaybeWithDoc :: Maybe (LHsDoc name) -> SDoc -> SDoc #

See `pprWithHsDoc`

module GHC.Hs.DocString

data ExtractedTHDocs #

Maps of docs that were added via Template Haskell's `putDoc`.

Constructors

ExtractedTHDocs |
Fields ethd_mod_header :: Maybe (HsDoc GhcRn) The added module header documentation, if it exists. ethd_decl_docs :: UniqMap Name (HsDoc GhcRn) The documentation added to declarations. ethd_arg_docs :: UniqMap Name (IntMap (HsDoc GhcRn)) The documentation added to function arguments. ethd_inst_docs :: UniqMap Name (HsDoc GhcRn) The documentation added to class and family instances.

data DocStructureItem #

A simplified version of `IE`.

Constructors

DsiSectionHeading !Int !(HsDoc GhcRn) |
DsiDocChunk !(HsDoc GhcRn) |
DsiNamedChunkRef !String |
DsiExports !DetOrdAvails |
DsiModExport |
- Fields !(NonEmpty ModuleName) We might re-export avails from multiple modules with a single export declaration. E.g. when we have
      module M (module X) where
      import R0 as X
      import R1 as X
Invariant: This list of ModuleNames must be sorted to guarantee interface file determinism. !DetOrdAvails Invariant: This list of Avails must be sorted to guarantee interface file determinism.

#### Instances

Instances details

NFData DocStructureItem # |
Instance details Defined in GHC.Hs.Doc Methods rnf :: DocStructureItem -> () #
Binary DocStructureItem # |
Instance details Defined in GHC.Hs.Doc Methods put_ :: WriteBinHandle -> DocStructureItem -> IO () # put :: WriteBinHandle -> DocStructureItem -> IO (Bin DocStructureItem) # get :: ReadBinHandle -> IO DocStructureItem #
Outputable DocStructureItem # |
Instance details Defined in GHC.Hs.Doc Methods ppr :: DocStructureItem -> SDoc #

type DocStructure = [DocStructureItem] #

data Docs #

Constructors

Docs |
Fields docs_mod_hdr :: Maybe (HsDoc GhcRn) Module header. docs_exports :: UniqMap Name (HsDoc GhcRn) Docs attached to module exports. docs_decls :: UniqMap Name [HsDoc GhcRn] Docs for declarations: functions, data types, instances, methods etc. A list because sometimes subsequent haddock comments can be combined into one docs_args :: UniqMap Name (IntMap (HsDoc GhcRn)) Docs for arguments. E.g. function arguments, method arguments. docs_structure :: DocStructure docs_named_chunks :: Map String (HsDoc GhcRn) Map from chunk name to content. This map will be empty unless we have an explicit export list from which we can reference the chunks. docs_haddock_opts :: Maybe String Haddock options from `OPTIONS_HADDOCK` or from `-haddock-opts`. docs_language :: Maybe Language The `Language` used in the module, for example `Haskell2010`. docs_extensions :: EnumSet Extension The full set of language extensions used in the module.

#### Instances

Instances details

NFData Docs # |
Instance details Defined in GHC.Hs.Doc Methods rnf :: Docs -> () #
Binary Docs # |
Instance details Defined in GHC.Hs.Doc Methods put_ :: WriteBinHandle -> Docs -> IO () # put :: WriteBinHandle -> Docs -> IO (Bin Docs) # get :: ReadBinHandle -> IO Docs #
Outputable Docs # |
Instance details Defined in GHC.Hs.Doc Methods ppr :: Docs -> SDoc #

emptyDocs :: Docs #