haskell-gi-0.26.10: Generate Haskell bindings for GObject Introspection capable libraries
Safe HaskellSafe-Inferred
LanguageHaskell2010

Data.GI.CodeGen.GtkDoc

Description

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

Synopsis

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",List [ListItem (GtkDoc [Literal "First item"]) [],ListItem (GtkDoc [Literal "Second item"]) []]]
>>> parseGtkDoc "Spaced list:\n\n- First item\n\n- Second item"
GtkDoc [Literal "Spaced list:\n",List [ListItem (GtkDoc [Literal "First item"]) [],ListItem (GtkDoc [Literal "Second item"]) []]]
>>> parseGtkDoc "List with urls:\n- [test](http://test)\n- ![](image.png)"
GtkDoc [Literal "List with urls:\n",List [ListItem (GtkDoc [ExternalLink (Link {linkName = "test", linkAddress = "http://test"})]) [],ListItem (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

show :: GtkDoc -> String

showList :: [GtkDoc] -> ShowS

Eq GtkDoc Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

(==) :: GtkDoc -> GtkDoc -> Bool

(/=) :: GtkDoc -> GtkDoc -> Bool

data Token Source #

A parsed gtk-doc token.

Constructors

Literal Text 
Comment Text 
Verbatim Text 
CodeBlock (Maybe Language) Text 
ExternalLink Link 
Image Link 
List [ListItem] 
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

show :: Token -> String

showList :: [Token] -> ShowS

Eq Token Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

(==) :: Token -> Token -> Bool

(/=) :: Token -> Token -> Bool

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

show :: Language -> String

showList :: [Language] -> ShowS

Eq Language Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

(==) :: Language -> Language -> Bool

(/=) :: Language -> Language -> Bool

data Link Source #

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

Constructors

Link 

Fields

Instances

data ListItem Source #

An item in a list, given by a list of lines (not including ending newlines). The list is always non-empty, so we represent it by the first line and then a possibly empty list with the rest of the lines.

Constructors

ListItem GtkDoc [GtkDoc] 

Instances

Instances details
Show ListItem Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

showsPrec :: Int -> ListItem -> ShowS

show :: ListItem -> String

showList :: [ListItem] -> ShowS

Eq ListItem Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

(==) :: ListItem -> ListItem -> Bool

(/=) :: ListItem -> ListItem -> Bool

data CRef Source #

A reference to some symbol in the API.

Instances

Instances details
Show CRef Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

showsPrec :: Int -> CRef -> ShowS

show :: CRef -> String

showList :: [CRef] -> ShowS

Eq CRef Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

(==) :: CRef -> CRef -> Bool

(/=) :: CRef -> CRef -> Bool

Ord CRef Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Methods

compare :: CRef -> CRef -> Ordering

(<) :: CRef -> CRef -> Bool

(<=) :: CRef -> CRef -> Bool

(>) :: CRef -> CRef -> Bool

(>=) :: CRef -> CRef -> Bool

max :: CRef -> CRef -> CRef

min :: CRef -> CRef -> CRef

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

show :: DocSymbolName -> String

showList :: [DocSymbolName] -> ShowS

Eq DocSymbolName Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

Ord DocSymbolName Source # 
Instance details

Defined in Data.GI.CodeGen.GtkDoc

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.