Tags In Docs

Here is a list of tags that can be found in GLib and GTK+ doc comments:

GTK+

Tag

Replacement

Status

<example>

Use markdown heading

Done

<refsect2>

# Markdown

Done

<title>

part of headings

Done

<figure>

Markdown img link

Done

<graphic>

combine with <figure>?

Done

<inlinegraphic>

Markdown "![alt](filename)"

Done

<informalexample>

|[ ]|

Done 723119

<note>

Markdown blockquote ">"

Done

<important>

Markdown blockquote ">"

Done

<warning>

Markdown blockquote ">"

Done

<para>

Markdown blank line

Done

<programlisting>

|[ ]|

723118, 723119

<footnote>

Done

<function>

Done

<manvolnum>

Done

<structfield>

Done

<structname>

# syntax

Done

<type>

Done

<classname>

Done

<emphasis>

Done

Values

Tag

Replacement

Status

<application>

Done

<firstterm>

Done

<literal>

Markdown (foo)

Done

<literallayout>

Done

<envar>

Markdown (foo)

Done

<filename>

Markdown (foo)

Done

<replaceable>

Done

<option>

Markdown (foo)

Done

<parameter>

@ or Markdown (\foo\)

Done

<screen>

Done

<keycombo><keycap>

Done

<tag>

Done

<quote>

“foo”

Done

<command>

Done

<guimenuitem>

Done

Blocks

Tag

Replacement

Status

<orderedlist>

Markdown list

Done

<itemizedlist>

Markdown list

Done

<listitem>

Remove

Done

<simplelist>

Markdown list

Done

<member>

Remove

Done

<table>

Done

<informaltable>

Done

<thead>

Done

<tbody>

Done

<row>

Done

<entry>

Done

<variablelist>

Markdown list

Done

<term>

Remove

Done

<varlistentry>

Remove

Done

<varname>

Remove

Done

Tag

Replacement

Status

<anchor>

Use heading

Done

<link>

Markdown [][]

Done

<ulink>

Markdown []()

Done

<xi:include>

Done

<xi:fallback>

Done

<xref linkend="">

Markdown [][]

Done

Caveats, cleanups

When replacing <programlisting> by |[ ]| check for escaping in the example: We were using various forms of escaping to protect not only against the C preprocessor spotting comment start/end but also against gtk-doc spotting shorthands (ie # or %). Also, we were using empty xml comments in some places, which won't work anymore:

  • /<!-- -->* has to be replaced by /*

  • %percnt;s has to be replaced by %s
  • &foo has to be replaced by &foo

  • foo(<!-- -->) has to be replaced by foo()

  • i < 1000 has to be replaced by i < 1000

A common idiom is #SomeStruct<!-- -->s. This is no longer necessary, since gtk-doc can deal with #SomeStructs now.

We frequently use /* ... */ in examples to indicate omissions. I think it looks nicer to just do ... without the comment

When adding class structs to the docs, we need to add /*< private >*/ to hide ugly things like reserved slots

GLib

Tag

Replacement

Status

<code>

Done

<command>

Done

<computeroutput>

Done

<emphasis>

Done

<entry>

<envar>

<example>

Done

<figure>

<filename>

<firstterm>

<footnote>

Remove

Done

<function>

()

Done

<indexterm>

Remove

Done

<informalexample>

Mostly done

<informaltable>

<itemizedlist>

markdown

Done

<listitem>

markdown

Done

<literal>

<manvolnum>

Done

<member>

markdown

Done

<note>

Done

<option>

<orderedlist>

markdown

Done

<para>

<primary>

Remove

Done

<programlisting>

Mostly done

<quote>

Done

<refsect2>

markdown

Done

<refsect3>

markdown

Done

<replaceable>

<row>

<screen>

<simplelist>

markdown

Done

<structname>

Remove

Done

<structfield>

@

Done

<table>

<tbody>

<term>

<thead>

<title>

<type>

Remove

Done

<ulink>

<varlistentry>

markdown

Done

<varname>

Done

<warning>

Done

<xi:include>

<xi:fallback>

How To

A starting point for migrating api-docs to markdown would be to check the existing tags:

find . \( -name "*.c" -o -name "*.h" \) -exec egrep "^ +\* " {} \;| egrep -o "</[a-zA-Z]+?>" | sort -f | uniq -i

See Also

Projects/GTK+/TagsInDocs (last edited 2014-02-18 19:35:21 by StefanSauer)