Tags In Docs
Here is a list of tags that can be found in GLib and GTK+ doc comments:
GTK+
Tag |
Replacement |
Status |
Use markdown heading |
Done |
|
Done |
||
part of headings |
Done |
|
Markdown img link |
Done |
|
combine with <figure>? |
Done |
|
Markdown "" |
Done |
|
|[ ]| |
Done 723119 |
|
Markdown blockquote ">" |
Done |
|
Markdown blockquote ">" |
Done |
|
Markdown blockquote ">" |
Done |
|
Markdown blank line |
Done |
|
|[ ]| |
||
|
Done |
|
|
Done |
|
|
Done |
|
|
Done |
|
# syntax |
Done |
|
|
Done |
|
|
Done |
|
|
Done |
Values
Tag |
Replacement |
Status |
|
Done |
|
|
Done |
|
Markdown (foo) |
Done |
|
|
Done |
|
Markdown (foo) |
Done |
|
Markdown (foo) |
Done |
|
|
Done |
|
Markdown (foo) |
Done |
|
@ or Markdown (\foo\) |
Done |
|
|
Done |
|
|
Done |
|
|
Done |
|
“foo” |
Done |
|
|
Done |
|
|
Done |
Blocks
Tag |
Replacement |
Status |
Markdown list |
Done |
|
Markdown list |
Done |
|
Remove |
Done |
|
Markdown list |
Done |
|
Remove |
Done |
|
|
Done |
|
|
Done |
|
|
Done |
|
|
Done |
|
|
Done |
|
|
Done |
|
Markdown list |
Done |
|
Remove |
Done |
|
Remove |
Done |
|
Remove |
Done |
Links
Tag |
Replacement |
Status |
Use heading |
Done |
|
Markdown [][] |
Done |
|
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