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
- | List [ListItem]
- | SectionHeader Int GtkDoc
- | SymbolRef CRef
newtype Language = Language Text
data Link = Link {
- linkName :: Text
- linkAddress :: Text
}
data ListItem = ListItem GtkDoc [GtkDoc]
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
- | 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",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 linkName :: Text linkAddress :: Text

Instances

Instances details

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

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 Methods (==) :: DocSymbolName -> DocSymbolName -> Bool # (/=) :: DocSymbolName -> DocSymbolName -> Bool #
Ord DocSymbolName Source #
Instance details Defined in Data.GI.CodeGen.GtkDoc Methods compare :: DocSymbolName -> DocSymbolName -> Ordering # (<) :: DocSymbolName -> DocSymbolName -> Bool # (<=) :: DocSymbolName -> DocSymbolName -> Bool # (>) :: DocSymbolName -> DocSymbolName -> Bool # (>=) :: DocSymbolName -> DocSymbolName -> Bool # max :: DocSymbolName -> DocSymbolName -> DocSymbolName # min :: DocSymbolName -> DocSymbolName -> DocSymbolName #

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.

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
CTypeRef Text
TypeRef DocSymbolName