GHC.Hs.Doc

ghc-9.14.0.20251028: The GHC API

Safe Haskell | None
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 Source #

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

data WithHsDocIdentifiers a pass Source #

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) Source # |
Instance details Defined in GHC.Hs.Doc Methods rnf :: WithHsDocIdentifiers a pass -> () Source #
Binary a => Binary (WithHsDocIdentifiers a GhcRn) Source # |
Instance details Defined in GHC.Hs.Doc Methods put_ :: WriteBinHandle -> WithHsDocIdentifiers a GhcRn -> IO () Source # put :: WriteBinHandle -> WithHsDocIdentifiers a GhcRn -> IO (Bin (WithHsDocIdentifiers a GhcRn)) Source # get :: ReadBinHandle -> IO (WithHsDocIdentifiers a GhcRn) Source #
Outputable a => Outputable (WithHsDocIdentifiers a pass) Source # | 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 Source #
(Eq (IdP pass), Eq a) => Eq (WithHsDocIdentifiers a pass) Source # |
Instance details Defined in GHC.Hs.Doc Methods (==) :: WithHsDocIdentifiers a pass -> WithHsDocIdentifiers a pass -> Bool Source # (/=) :: WithHsDocIdentifiers a pass -> WithHsDocIdentifiers a pass -> Bool Source #
(Data pass, Data (IdP pass), Data a) => Data (WithHsDocIdentifiers a pass) Source # |
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) Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (WithHsDocIdentifiers a pass) Source # toConstr :: WithHsDocIdentifiers a pass -> Constr Source # dataTypeOf :: WithHsDocIdentifiers a pass -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (WithHsDocIdentifiers a pass)) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (WithHsDocIdentifiers a pass)) Source # gmapT :: (forall b. Data b => b -> b) -> WithHsDocIdentifiers a pass -> WithHsDocIdentifiers a pass Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> WithHsDocIdentifiers a pass -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> WithHsDocIdentifiers a pass -> r Source # gmapQ :: (forall d. Data d => d -> u) -> WithHsDocIdentifiers a pass -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> WithHsDocIdentifiers a pass -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> WithHsDocIdentifiers a pass -> m (WithHsDocIdentifiers a pass) Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> WithHsDocIdentifiers a pass -> m (WithHsDocIdentifiers a pass) Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> WithHsDocIdentifiers a pass -> m (WithHsDocIdentifiers a pass) Source #

hsDocIds :: WithHsDocIdentifiers a GhcRn -> NameSet Source #

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

type LHsDoc pass = Located (HsDoc pass) Source #

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

Print a doc with its identifiers, useful for debugging

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

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 Source #

See `pprWithHsDoc`

module GHC.Hs.DocString

data ExtractedTHDocs Source #

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 Source #

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

type DocStructure = [DocStructureItem] Source #

data Docs Source #

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

emptyDocs :: Docs Source #