[valadoc] doclets/gtkdoc: Add type_id and comments to non-GObject classes

[Luca Bruno <lucabru src gnome org>]

commit e81df5494f4090bd2c1e505e7431a612396c22f0
Author: Luca Bruno <lethalman88 gmail com>
Date:   Fri Aug 20 11:13:40 2010 +0200

    doclets/gtkdoc: Add type_id and comments to non-GObject classes

 src/doclets/gtkdoc/generator.vala |   69 ++++++++++++++++++++++++++++++------
 src/doclets/gtkdoc/utils.vala     |    4 ++
 src/libvaladoc/api/class.vala     |    6 +++-
 3 files changed, 66 insertions(+), 13 deletions(-)
---
diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index 15d12b8..af91212 100644
--- a/src/doclets/gtkdoc/generator.vala
+++ b/src/doclets/gtkdoc/generator.vala
@@ -202,7 +202,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		return gcomment;
 	}
 
-	private GComment add_comment (string filename, string symbol, Comment? comment) {
+	private GComment add_comment (string filename, string symbol, Comment? comment = null) {
 		var file_data = get_file_data (filename);
 		var gcomment = create_gcomment (symbol, comment);
 		file_data.comments.add (gcomment);
@@ -328,6 +328,8 @@ public class Gtkdoc.Generator : Api.Visitor {
 			current_dbus_interface = new DBus.Interface (settings.pkg_name, cl.get_dbus_name ());
 		}
 
+		var gcomment = add_symbol (cl.get_filename(), cl.get_type_id());
+		gcomment.brief_comment = "The type for %s.".printf (get_docbook_link (cl));
 
 		cl.accept_all_children (this);
 
@@ -339,20 +341,63 @@ public class Gtkdoc.Generator : Api.Visitor {
 			dbus_interfaces.add (current_dbus_interface);
 		}
 
+		if (cl.is_fundamental && cl.base_type == null) {
+			var filename = cl.get_filename ();
+
+			// ref
+			current_headers.clear ();
+			add_custom_header ("instance", "a %s.".printf (get_docbook_link (cl)));
+			gcomment = add_symbol (filename, cl.get_ref_function_cname ());
+			gcomment.brief_comment = "Increases the reference count of @object.";
+			gcomment.returns = "the same @object";
+
+			// unref
+			current_headers.clear ();
+			add_custom_header ("instance", "a %s.".printf (get_docbook_link (cl)));
+			gcomment = add_symbol (filename, cl.get_unref_function_cname ());
+			gcomment.brief_comment = "Decreases the reference count of @object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).";
+
+			// param_spec
+			current_headers.clear ();
+			add_custom_header ("name", "canonical name of the property specified");
+			add_custom_header ("nick", "nick name for the property specified");
+			add_custom_header ("blurb", "description of the property specified");
+			add_custom_header ("object_type", "%s derived type of this property".printf (get_docbook_type_link (cl)));
+			add_custom_header ("flags", "flags for the property specified");
+			gcomment = add_symbol (filename, cl.get_param_spec_function_cname ());
+			gcomment.brief_comment = "Creates a new <link linkend=\"GParamSpecBoxed\"><type>GParamSpecBoxed</type></link> instance specifying a %s derived property.".printf (get_docbook_type_link (cl));
+			gcomment.long_comment = "See <link linkend=\"g-param-spec-internal\"><function>g_param_spec_internal()</function></link> for details on property names.";
+
+			// value_set
+			current_headers.clear ();
+			add_custom_header ("value", "a valid <link linkend=\"GValue\"><type>GValue</type></link> of %s derived type".printf (get_docbook_type_link (cl)));
+			add_custom_header ("v_object", "object value to be set");
+			gcomment = add_symbol (filename, cl.get_set_value_function_cname ());
+			gcomment.brief_comment = "Set the contents of a %s derived <link linkend=\"GValue\"><type>GValue</type></link> to @v_object.".printf (get_docbook_type_link (cl));
+			gcomment.long_comment = "<link linkend=\"%s\"><function>%s()</function></link> increases the reference count of @v_object (the <link linkend=\"GValue\"><type>GValue</type></link> holds a reference to @v_object). If you do not wish to increase the reference count of the object (i.e. you wish to pass your current reference to the <link linkend=\"GValue\"><type>GValue</type></link> because you no longer need it), use <link linkend=\"%s\"><function>%s()</function></link> instead.
+
+It is important that your <link linkend=\"GValue\"><type>GValue</type></link> holds a reference to @v_object (either its own, or one it has taken) to ensure that the object won't be destroyed while the <link linkend=\"GValue\"><type>GValue</type></link> still exists).".printf (to_docbook_id (cl.get_set_value_function_cname ()), cl.get_set_value_function_cname (), to_docbook_id (cl.get_take_value_function_cname ()), cl.get_take_value_function_cname ());
+
+			// value_get
+			current_headers.clear ();
+			add_custom_header ("value", "a valid <link linkend=\"GValue\"><type>GValue</type></link> of %s derived type".printf (get_docbook_type_link (cl)));
+			gcomment = add_symbol (filename, cl.get_get_value_function_cname ());
+			gcomment.brief_comment = "Get the contents of a %s derived <link linkend=\"GValue\"><type>GValue</type></link>.".printf (get_docbook_type_link (cl));
+			gcomment.returns = "object contents of @value";
+
+			// value_take
+			current_headers.clear ();
+			add_custom_header ("value", "a valid <link linkend=\"GValue\"><type>GValue</type></link> of %s derived type".printf (get_docbook_type_link (cl)));
+			add_custom_header ("v_object", "object value to be set");
+			gcomment = add_symbol (filename, cl.get_take_value_function_cname ());
+			gcomment.brief_comment = "Sets the contents of a %s derived <link linkend=\"GValue\"><type>GValue</type></link> to @v_object and takes over the ownership of the callers reference to @v_object; the caller doesn't have to unref it any more (i.e. the reference count of the object is not increased).".printf (get_docbook_type_link (cl));
+			gcomment.long_comment = "If you want the GValue to hold its own reference to @v_object, use <link linkend=\"%s\"><function>%s()</function></link> instead.".printf (to_docbook_id (cl.get_set_value_function_cname ()), cl.get_set_value_function_cname ());
+		}
+
 		current_cname = old_cname;
 		current_headers = old_headers;
 		current_class = old_class;
 		current_dbus_interface = old_dbus_interface;
-
-		if (cl.is_fundamental && cl.base_type == null) {
-			var filename = cl.get_filename ();
-			add_symbol (filename, cl.get_ref_function_cname ());
-			add_symbol (filename, cl.get_unref_function_cname ());
-			add_symbol (filename, cl.get_param_spec_function_cname ());
-			add_symbol (filename, cl.get_set_value_function_cname ());
-			add_symbol (filename, cl.get_get_value_function_cname ());
-			add_symbol (filename, cl.get_take_value_function_cname ());
-		}
 	}
 
 	public override void visit_struct (Api.Struct st) {
@@ -578,7 +623,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 			if (!m.is_static) {
 				finish_gcomment.headers.add (new Header ("self", "the %s instance".printf (get_docbook_link (m.parent))));
 			}
-			finish_gcomment.headers.add (new Header ("_res_", "a GAsyncResult"));
+			finish_gcomment.headers.add (new Header ("_res_", "a <link linkend=\"GAsyncResult\"><type>GAsyncResult</type></link>"));
 			if (error_header != null) {
 				finish_gcomment.headers.add (error_header);
 			}
diff --git a/src/doclets/gtkdoc/utils.vala b/src/doclets/gtkdoc/utils.vala
index f3263dc..59e2df8 100644
--- a/src/doclets/gtkdoc/utils.vala
+++ b/src/doclets/gtkdoc/utils.vala
@@ -75,6 +75,10 @@ namespace Gtkdoc {
 		return null;
 	}
 
+	public string get_docbook_type_link (Api.Class cls) {
+		return """<link linkend="%s:CAPS"><literal>%s</literal></link>""".printf (to_docbook_id (cls.get_type_id ()), cls.get_type_id ());
+	}
+
 	public string? get_docbook_link (Api.Item item, bool is_dbus = false, bool is_async_finish = false) {
 		if (item is Api.Method) {
 			string name;
diff --git a/src/libvaladoc/api/class.vala b/src/libvaladoc/api/class.vala
index 0ed0fd5..668b788 100644
--- a/src/libvaladoc/api/class.vala
+++ b/src/libvaladoc/api/class.vala
@@ -46,7 +46,11 @@ public class Valadoc.Api.Class : TypeSymbol {
 	}
 
 	public string? get_cname () {
-		return this.vclass.get_cname();
+		return this.vclass.get_cname ();
+	}
+
+	public string? get_type_id () {
+		return this.vclass.get_type_id ();
 	}
 
 	public string? get_ref_function_cname () {