Documenting the code
GTK-Doc uses source code comment with a special syntax for code documentation. Further it retrieves information about your project structure from other sources. During the next section you will find all information about the syntax of the comments.
The GTK-Doc scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can hint GTK-Doc to skip over them.

GTK-Doc comment block

#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif

Limitations
Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations.

Documentation comments
A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the GTK-Doc tools.

GTK-Doc comment block

/**
 * identifier:
 * documentation ...
 */

The 'identifier' is one line with the name of the item the comment is related to. The syntax differs a little depending on the item. (TODO add table showing identifiers)
The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank). This is useful in preformatted text (code listings).
When documenting code, describe two aspects:
What it is: The name for a class or function can sometimes be misleading for people coming from a different background.
What it does: Tell about common uses. Put it in relation with the other API.
One advantage of hyper-text over plain-text is the ability to have links in the document. Writing the correct markup for a link can be tedious though. GTK-Doc comes to help by providing several useful abbreviations.
Use function() to refer to functions or macros which take arguments.
Use @param to refer to parameters. Also use this when referring to parameters of other functions, related to the one being described.
Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
Use #symbol to refer to other types of symbol, e.g. structs and enums and macros which don't take arguments.
Use #Object::signal to refer to a GObject signal.
Use #Object:property to refer to a GObject property.
Use #Struct.field to refer to a field inside a structure and #GObjectClass.foo_bar() to refer to a vmethod.
If you need to use the special characters '<', '>', '()', '@', '%', or '#' in your documentation without GTK-Doc changing them you can use the XML entities "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" and "&num;" respectively or escape them with a backslash '\'.
DocBook can do more than just links. One can also have lists, examples, headings, and images. As of version 1.20, the preferred way is to use a subset of the basic text formatting syntax called Markdown. On older GTK-Doc versions any documentation that includes Markdown will be rendered as is. For example, list items will appear as lines starting with a dash.
While markdown is now preferred one can mix both. One limitation here is that one can use docbook xml within markdown, but markdown within docbook xml is not supported.
In older GTK-Doc releases, if you need support for additional formatting, you would need to enable the usage of docbook XML tags inside doc-comments by putting --xml-mode (or --sgml-mode) in the variable MKDB_OPTIONS inside Makefile.am.

GTK-Doc comment block using Markdown

/**
 * identifier:
 *
 * documentation paragraph ...
 *
 * # Sub Heading #
 *
 * ## Second Sub Heading
 *
 * # Sub Heading With a Link Anchor # {#heading-two}
 *
 * more documentation:
 *
 * - list item 1
 *
 *   Paragraph inside a list item.
 *
 * - list item 2
 *
 * 1. numbered list item
 *
 * 2. another numbered list item
 *
 * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 *
 * ![an inline image](plot-result.png)
 *
 * [A link to the heading anchor above][heading-two]
 *
 * A C-language example:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */

More examples of what markdown tags are supported can be found in the GTK Documentation Markdown Syntax Reference.
As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good to comment those symbols too. This helps other developers to understand your code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to add another '*' in the comment block and insert the symbol name at the right place inside the sections file.

Documenting sections
Each section of the documentation contains information about one class or module. To introduce the component one can write a section block. The short description is also used inside the table of contents. All the @fields are optional.

Section comment block

/**
 * SECTION:meepapp
 * @short_description: the application class
 * @title: Meep application
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * The application class handles ...
 */

SECTION:<name> 	 The name links the section documentation to the respective part in the <package>-sections.txt file. The name given here should match the <FILE> tag in the <package>-sections.txt file.
@short_description 	 A one line description of the section, that later will appear after the links in the TOC and at the top of the section page.
@title 	 The section title defaults to <name> from the SECTION declaration. It can be overridden with the @title field.
@section_id 	 Overrides the use of title as a section identifier. For GObjects the <title> is used as a section_id and for other sections it is <MODULE>-<title>.
@see_also 	 A list of symbols that are related to this section.
@stability 	 An informal description of the stability level this API has. We recommend the use of one of these terms:
Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications.
Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next.
Private - An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways.
Internal - An interface that is internal to a module and does not require end-user documentation. Functions that are undocumented are assumed to be Internal.
@include 	 The #include files to show in the section synopsis (a comma separated list), overriding the global value from the section file or command line. This item is optional.
@image 	 The image to display at the top of the reference page for this section. This will often be some sort of a diagram to illustrate the visual appearance of a class or a diagram of its relationship to other classes. This item is optional.
To avoid unnecessary recompilation after doc-changes put the section docs into the c-source where possible.

Documenting symbols
Each symbol (function, macro, struct, enum, signal and property) is documented in a separate block. The block is best placed close to the definition of the symbols so that it is easy to keep them in sync. Thus functions are usually documented in the c-source and macros, structs and enums in the header file.

General tags
You can add versioning information to all documentation elements to tell when an API was introduced, or when it was deprecated.

Versioning Tags
Since: 	 Description since which version of the code the API is available.
Deprecated: 	 Paragraph denoting that this function should no be used anymore. The description should point the reader to the new API.
You can also add stability information to all documentation elements to indicate whether API stability is guaranteed for them for all future minor releases of the project.
The default stability level for all documentation elements can be set by passing the --default-stability argument to gtkdoc-mkdb with one of the values below.

Stability Tags
Stability: Stable 	 Mark the element as stable. This is for public APIs which are guaranteed to remain stable for all future minor releases of the project.
Stability: Unstable 	 Mark the element as unstable. This is for public APIs which are released as a preview before being stabilised.
Stability: Private 	 Mark the element as private. This is for interfaces which can be used by tightly coupled modules, but not by arbitrary third parties.

General tags

/**
 * foo_get_bar:
 * @foo: some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: @foo's bar
 *
 * Since: 2.6
 * Deprecated: 2.12: Use foo_baz_get_bar() instead.
 */
Bar *
foo_get_bar(Foo *foo)
{
...

Annotations
Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list of the supported tags can be found on the wiki.

Annotations

/**
 * foo_get_bar: (annotation)
 * @foo: (annotation): some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: (annotation): @foo's bar
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
 *                                    (and another annotation)
 * @foo: (annotation) (another annotation): some foo
 *
 * Sets bar on @foo.
 */

Function comment block
Please remember to:
Document whether returned objects, lists, strings, etc, should be freed/unrefed/released.
Document whether parameters can be NULL, and what happens if they are.
Mention interesting pre-conditions and post-conditions where appropriate.
Gtk-doc assumes all symbols (macros, functions) starting with '_' are private. They are treated like static functions.

Function comment block

/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * @...: a %NULL-terminated list of bars
 *
 * The function description goes here. You can use @par1 to refer to parameters
 * so that they are highlighted in the output. You can also use %constant
 * for constants, function_name2() for functions and #GtkWidget for links to
 * other declarations (which may be documented elsewhere).
 *
 * Returns: an integer.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */

Function tags
Returns: 	 Paragraph describing the returned result.
@...: 	 In case the function has variadic arguments, you should use this tag (@Varargs: does also work for historic reasons).

Property comment block

Property comment block

/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

Signal comment block
Please remember to:
Document when the signal is emitted and whether it is emitted before or after other signals.
Document what an application might do in the signal handler.

Signal comment block

/**
 * FooWidget::foobarized:
 * @widget: the widget that received the signal
 * @foo: some foo
 * @bar: some bar
 *
 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
 */
foo_signals[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...

Struct comment block

Struct comment block

/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;

Use /*< private >*/ before the private struct fields you want to hide. Use /*< public >*/ for the reverse behaviour.
If the first field is "g_iface", "parent_instance" or "parent_class" it will be considered private automatically and doesn't need to be mentioned in the comment block.
Struct comment blocks can also be used for GObjects and GObjectClasses. It is usually a good idea to add a comment block for a class, if it has vmethods (as this is how they can be documented). For the GObject itself one can use the related section docs, having a separate block for the instance struct would be useful if the instance has public fields. One disadvantage here is that this creates two index entries of the same name (the structure and the section).

Enum comment block

Enum comment block

/**
 * Something:
 * @SOMETHING_FOO: something foo
 * @SOMETHING_BAR: something bar
 *
 * Enum values used for the thing, to specify the thing.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

Use /*< private >*/ before the private enum values you want to hide. Use /*< public >*/ for the reverse behaviour.

Inline program documentation
You can document programs and their commandline interface using inline documentation.

Tags
PROGRAM 	 Defines the start of a program documentation.
@short_description: 	 Defines a short description of the program. (Optional)
@synopsis: 	 Defines the arguments, or list of arguments that the program can take. (Optional)
@see_also: 	 See Also manual page section. (Optional)
@arg: 	 Argument(s) passed to the program and their description. (Optional)
Description: 	 A longer description of the program.
Returns: 	 Specify what value(s) the program returns. (Optional)

Example of program documentation.

Program documentation block

/**
 * PROGRAM:test-program
 * @short_description: A test program
 * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
 * @see_also: test(1)
 * @--arg1 *arg*: set arg1 to *arg*
 * @--arg2 *arg*: set arg2 to *arg*
 * @-v, --version: Print the version number
 * @-h, --help: Print the help message
 *
 * Long description of program.
 *
 * Returns: Zero on success, non-zero on failure
 */
int main(int argc, char *argv[])
{
	return 0;
}

Useful DocBook tags
Here are some DocBook tags which are most useful when documenting the code.
To link to another section in the GTK docs:

<link linkend="glib-Hash-Tables">Hash Tables</link>

The linkend is the SGML/XML id on the top item of the page you want to link to. For most pages this is currently the part ("gtk", "gdk", "glib") and then the page title ("Hash Tables"). For widgets it is just the class name. Spaces and underscores are converted to '-' to conform to SGML/XML.
To refer to an external function, e.g. a standard C function:

<function>...</function>

To include example code:

<example>
  <title>Using a GHashTable.</title>
  <programlisting language="C">
      ...
  </programlisting>
</example>

or possibly this, for very short code fragments which don't need a title:

<informalexample>
  <programlisting language="C">
  ...
  </programlisting>
</informalexample>

In both cases, the language attribute is optional and is used as a hint to the syntax highlighting engine (pygments for html output). For the latter GTK-Doc also supports an abbreviation:

|[<!-- language="C" -->
  ...
]|

To include bulleted lists:

<itemizedlist>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
</itemizedlist>

To include a note which stands out from the text:

<note>
  <para>
    Make sure you free the data after use.
  </para>
</note>

To refer to a type:

<type>unsigned char</type>

To refer to an external structure (not one described in the GTK docs):

<structname>XFontStruct</structname>

To refer to a field of a structure:

<structfield>len</structfield>

To refer to a class name, we could possibly use:

<classname>GtkWidget</classname>

but you'll probably be using #GtkWidget instead (to automatically create a link to the GtkWidget page - see the abbreviations).
To emphasize text:

<emphasis>This is important</emphasis>

For filenames use:

<filename>/home/user/documents</filename>

To refer to keys use:

<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>