[gtk-doc] docs: Add a section for the gobject annotations.

[Stefan Kost <stefkost src gnome org>]

commit cf80ebf431402624373a4f237f170ac9e31614e9
Author: Stefan Sauer <ensonic users sf net>
Date:   Fri Apr 17 20:38:23 2015 +0200

    docs: Add a section for the gobject annotations.

 help/manual/C/index.docbook |   47 ++++++++++++++++++++++++++++++++----------
 1 files changed, 36 insertions(+), 11 deletions(-)
---
diff --git a/help/manual/C/index.docbook b/help/manual/C/index.docbook
index 5c2f914..666e7e0 100644
--- a/help/manual/C/index.docbook
+++ b/help/manual/C/index.docbook
@@ -1053,10 +1053,10 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
           </varlistentry>
         </variablelist>
 
-          <para>
-            (FIXME : Stability information)
-          </para>
-
+        <para>
+          (FIXME : Stability information)
+        </para>
+        
         <example><title>General tags</title>
           <programlisting><![CDATA[
 /**
@@ -1078,6 +1078,38 @@ foo_get_bar(Foo *foo)
         </example>
       </sect2>
 
+      <sect2><title>Annotations</title>
+
+        <para>
+          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 bingings. A detailed list
+          of the supported tags can be found on 
+          <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations"; type="http">the wiki</ulink>.
+        </para>
+
+        <example><title>Annotations</title>
+          <programlisting><![CDATA[
+/**
+ * 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.
+ */
+]]></programlisting>
+        </example>
+      </sect2>
+
       <sect2><title>Function comment block</title>
 
         <para>
@@ -1107,13 +1139,6 @@ foo_get_bar(Foo *foo)
           private. They are treated like static functions.
         </para>
 
-        <para>
-          <!-- FIXME: we should ideally link/describe the gobject introspection
-          annotation tag -->
-          Also, take a look at GObject Introspection annotation tags:
-          http://live.gnome.org/GObjectIntrospection/Annotations
-        </para>
-
         <example><title>Function comment block</title>
           <programlisting><![CDATA[
 /**