haskell-gi-0.26.17: Generate Haskell bindings for GObject Introspection capable libraries

Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.GI.CodeGen.GtkDoc

Description

A parser for gtk-doc formatted documentation, see https://developer.gnome.org/gtk-doc-manual/ for the spec.

Synopsis

- parseGtkDoc :: Text -> GtkDoc
- newtype GtkDoc = GtkDoc [Token]
- data Token
  - = Literal Text
  - | Comment Text
  - | Verbatim Text
  - | CodeBlock (Maybe Language) Text
  - | ExternalLink Link
  - | Image Link
  - | UnnumberedList [GtkDoc]
  - | NumberedList [(Text, GtkDoc)]
  - | SectionHeader Int GtkDoc
  - | SymbolRef CRef
- newtype Language = Language Text
- data Link = Link {
  - linkName :: Text
  - linkAddress :: Text
  }
- data CRef
  - = FunctionRef DocSymbolName
  - | OldFunctionRef Text
  - | MethodRef DocSymbolName Text
  - | ParamRef Text
  - | ConstantRef Text
  - | SignalRef DocSymbolName Text
  - | OldSignalRef Text Text
  - | LocalSignalRef Text
  - | PropertyRef DocSymbolName Text
  - | OldPropertyRef Text Text
  - | VMethodRef Text Text
  - | VFuncRef DocSymbolName Text
  - | StructFieldRef Text Text
  - | EnumMemberRef DocSymbolName Text
  - | CTypeRef Text
  - | TypeRef DocSymbolName
- data DocSymbolName
  - = RelativeName Text
  - | AbsoluteName Text Text
- docName :: Name -> DocSymbolName
- resolveDocSymbol :: DocSymbolName -> Text -> Name

# Documentation

parseGtkDoc :: Text -> GtkDoc Source #

Parse the given gtk-doc formatted documentation.

### Examples

Expand

    >>> parseGtkDoc ""
    GtkDoc []

    >>> parseGtkDoc "func()"
    GtkDoc [SymbolRef (OldFunctionRef "func")]

    >>> parseGtkDoc "literal"
    GtkDoc [Literal "literal"]

    >>> parseGtkDoc "This is a long literal"
    GtkDoc [Literal "This is a long literal"]

    >>> parseGtkDoc "Call foo() for free cookies"
    GtkDoc [Literal "Call ",SymbolRef (OldFunctionRef "foo"),Literal " for free cookies"]

    >>> parseGtkDoc "The signal ::activate is related to gtk_button_activate()."
    GtkDoc [Literal "The signal ",SymbolRef (LocalSignalRef "activate"),Literal " is related to ",SymbolRef (OldFunctionRef "gtk_button_activate"),Literal "."]

    >>> parseGtkDoc "The signal ##%#GtkButton::activate is related to gtk_button_activate()."
    GtkDoc [Literal "The signal ##%",SymbolRef (OldSignalRef "GtkButton" "activate"),Literal " is related to ",SymbolRef (OldFunctionRef "gtk_button_activate"),Literal "."]

    >>> parseGtkDoc "# A section\n\n## and a subsection ##\n"
    GtkDoc [SectionHeader 1 (GtkDoc [Literal "A section"]),Literal "\n",SectionHeader 2 (GtkDoc [Literal "and a subsection "])]

    >>> parseGtkDoc "Compact list:\n- First item\n- Second item"
    GtkDoc [Literal "Compact list:\n",UnnumberedList [GtkDoc [Literal "First item"],GtkDoc [Literal "Second item"]]]

    >>> parseGtkDoc "Spaced list:\n\n- First item\n\n- Second item"
    GtkDoc [Literal "Spaced list:\n\n",UnnumberedList [GtkDoc [Literal "First item"],GtkDoc [Literal "Second item"]]]

    >>> parseGtkDoc "List with urls:\n- [test](http://test)\n- ![](image.png)"
    GtkDoc [Literal "List with urls:\n",UnnumberedList [GtkDoc [ExternalLink (Link {linkName = "test", linkAddress = "http://test"})],GtkDoc [Image (Link {linkName = "", linkAddress = "image.png"})]]]

newtype GtkDoc Source #

A parsed gtk-doc with fully resolved references.

Constructors

GtkDoc [Token] |

#### Instances

Instances details

Show GtkDoc Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods showsPrec :: Int -> GtkDoc -> ShowS Source # show :: GtkDoc -> String Source # showList :: [GtkDoc] -> ShowS Source #
Eq GtkDoc Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods (==) :: GtkDoc -> GtkDoc -> Bool Source # (/=) :: GtkDoc -> GtkDoc -> Bool Source #

data Token Source #

A parsed gtk-doc token.

Constructors

Literal Text |
Comment Text |
Verbatim Text |
CodeBlock (Maybe Language) Text |
ExternalLink Link |
Image Link |
UnnumberedList [GtkDoc] | An unnumbered list of items.
NumberedList [(Text, GtkDoc)] | A list of numbered list items. The first element in the pair is the index.
SectionHeader Int GtkDoc | A section header of the given depth.
SymbolRef CRef |

#### Instances

Instances details

Show Token Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods showsPrec :: Int -> Token -> ShowS Source # show :: Token -> String Source # showList :: [Token] -> ShowS Source #
Eq Token Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods (==) :: Token -> Token -> Bool Source # (/=) :: Token -> Token -> Bool Source #

newtype Language Source #

The language for an embedded code block.

Constructors

Language Text |

#### Instances

Instances details

Show Language Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods showsPrec :: Int -> Language -> ShowS Source # show :: Language -> String Source # showList :: [Language] -> ShowS Source #
Eq Language Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods (==) :: Language -> Language -> Bool Source # (/=) :: Language -> Language -> Bool Source #

data Link Source #

A link to a resource, either offline or a section of the documentation.

Constructors

Link |

Fields

- linkName :: Text
- linkAddress :: Text

#### Instances

Instances details

Show Link Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods showsPrec :: Int -> Link -> ShowS Source # show :: Link -> String Source # showList :: [Link] -> ShowS Source #
Eq Link Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods (==) :: Link -> Link -> Bool Source # (/=) :: Link -> Link -> Bool Source #

data CRef Source #

A reference to some symbol in the API.

Constructors

FunctionRef DocSymbolName |
OldFunctionRef Text |
MethodRef DocSymbolName Text |
ParamRef Text |
ConstantRef Text |
SignalRef DocSymbolName Text |
OldSignalRef Text Text |
LocalSignalRef Text |
PropertyRef DocSymbolName Text |
OldPropertyRef Text Text |
VMethodRef Text Text |
VFuncRef DocSymbolName Text |
StructFieldRef Text Text |
EnumMemberRef DocSymbolName Text |
CTypeRef Text |
TypeRef DocSymbolName |

#### Instances

Instances details

Show CRef Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods showsPrec :: Int -> CRef -> ShowS Source # show :: CRef -> String Source # showList :: [CRef] -> ShowS Source #
Eq CRef Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods (==) :: CRef -> CRef -> Bool Source # (/=) :: CRef -> CRef -> Bool Source #
Ord CRef Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods compare :: CRef -> CRef -> Ordering Source # (<) :: CRef -> CRef -> Bool Source # (<=) :: CRef -> CRef -> Bool Source # (>) :: CRef -> CRef -> Bool Source # (>=) :: CRef -> CRef -> Bool Source # max :: CRef -> CRef -> CRef Source # min :: CRef -> CRef -> CRef Source #

data DocSymbolName Source #

Reference to a name (of a class, for instance) in the documentation. It can be either relative to the module where the documentation is, of in some other namespace.

Constructors

RelativeName Text | The symbol without a namespace specified
AbsoluteName Text Text | Namespace and symbol

#### Instances

Instances details

Show DocSymbolName Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods showsPrec :: Int -> DocSymbolName -> ShowS Source # show :: DocSymbolName -> String Source # showList :: [DocSymbolName] -> ShowS Source #
Eq DocSymbolName Source # |
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods (==) :: DocSymbolName -> DocSymbolName -> Bool Source # (/=) :: DocSymbolName -> DocSymbolName -> Bool Source #
Ord DocSymbolName Source # |

Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

compare :: DocSymbolName -> DocSymbolName -> Ordering Source #

(<) :: DocSymbolName -> DocSymbolName -> Bool Source #

(<=) :: DocSymbolName -> DocSymbolName -> Bool Source #

(>) :: DocSymbolName -> DocSymbolName -> Bool Source #

(>=) :: DocSymbolName -> DocSymbolName -> Bool Source #

max :: DocSymbolName -> DocSymbolName -> DocSymbolName Source #

min :: DocSymbolName -> DocSymbolName -> DocSymbolName Source #

docName :: Name -> DocSymbolName Source #

Turn an ordinary `Name` into a `DocSymbolName`

resolveDocSymbol :: DocSymbolName -> Text -> Name Source #

Return a `Name` from a potentially relative `DocSymbolName`, using the provided default namespace if the name is relative.