[valadoc] doclets/gtkdoc: Split async method documentation with _finish

[Luca Bruno <lucabru src gnome org>]

commit 1bb09f8361572f136cfd9cc1a935a21a7840c9c7
Author: Luca Bruno <lethalman88 gmail com>
Date:   Mon Aug 2 13:50:15 2010 +0200

    doclets/gtkdoc: Split async method documentation with _finish

 src/doclets/gtkdoc/commentconverter.vala |    8 ++----
 src/doclets/gtkdoc/gcomment.vala         |    6 +++++
 src/doclets/gtkdoc/generator.vala        |   35 +++++++++++++++++++++++------
 src/doclets/gtkdoc/utils.vala            |    8 +++++-
 4 files changed, 42 insertions(+), 15 deletions(-)
---
diff --git a/src/doclets/gtkdoc/commentconverter.vala b/src/doclets/gtkdoc/commentconverter.vala
index 3f183ee..0346776 100644
--- a/src/doclets/gtkdoc/commentconverter.vala
+++ b/src/doclets/gtkdoc/commentconverter.vala
@@ -42,19 +42,15 @@ public class Gtkdoc.CommentConverter : ContentVisitor {
 	public string returns;
 	public Gee.List<Header> headers = new Gee.LinkedList<Header> ();
 	public Gee.List<Header> versioning = new Gee.LinkedList<Header> ();
+	public string[] see_also = new string[]{};
 
 	private StringBuilder current_builder = new StringBuilder ();
 	private bool in_brief_comment = true;
-	private string[] see_also = new string[]{};
 
 	public void convert (Comment comment, bool is_dbus = false) {
 		this.is_dbus = is_dbus;
 		comment.accept (this);
 
-		if (see_also.length > 0) {
-			current_builder.append_printf ("<para><emphasis>See also</emphasis>: %s</para>", string.joinv (", ", see_also));
-		}
-
 		long_comment = current_builder.str.strip ();
 		if (long_comment == "") {
 			long_comment = null;
@@ -245,7 +241,9 @@ public class Gtkdoc.CommentConverter : ContentVisitor {
 			versioning.add (header);
 		} else if (t is Taglets.See) {
 			var see = (Taglets.See)t;
+			var see_also = this.see_also; // vala bug
 			see_also += get_docbook_link (see.symbol, is_dbus) ?? see.symbol_name;
+			this.see_also = see_also;
 		} else if (t is Taglets.Link) {
 			((Taglets.Link)t).produce_content().accept (this);
 		} else {
diff --git a/src/doclets/gtkdoc/gcomment.vala b/src/doclets/gtkdoc/gcomment.vala
index 0ad68c2..e4549fa 100644
--- a/src/doclets/gtkdoc/gcomment.vala
+++ b/src/doclets/gtkdoc/gcomment.vala
@@ -29,6 +29,7 @@ public class Gtkdoc.GComment {
 	public string returns;
 	public string[] returns_annotations;
 	public Gee.List<Header> versioning = new Gee.LinkedList<Header> ();
+	public string[] see_also;
 
 	public string to_string () {
 		var builder = new StringBuilder ();
@@ -63,6 +64,10 @@ public class Gtkdoc.GComment {
 			builder.append_printf  ("\n * \n * %s", commentize (long_comment));
 		}
 
+		if (see_also.length > 0) {
+			builder.append_printf ("\n * \n * <emphasis>See also</emphasis>: %s", string.joinv (", ", see_also));
+		}
+
 		if (returns != null || returns_annotations.length > 0) {
 			builder.append ("\n * \n * Returns:");
 			if (returns_annotations != null) {
@@ -90,6 +95,7 @@ public class Gtkdoc.GComment {
 				}
 			}
 		}
+
 		builder.append ("\n */");
 		return builder.str;
 	}
diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index f347886..7927181 100644
--- a/src/doclets/gtkdoc/generator.vala
+++ b/src/doclets/gtkdoc/generator.vala
@@ -27,7 +27,7 @@ using Valadoc.Content;
 public class Gtkdoc.Generator : Api.Visitor {
 	class FileData {
 		public string filename;
-		public Gee.List<string> comments;
+		public Gee.List<GComment> comments;
 		public Gee.List<string> section_lines;
 	}
 
@@ -68,7 +68,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 			}
 
 			foreach (var comment in file_data.comments) {
-				cwriter.write_line (comment);
+				cwriter.write_line (comment.to_string ());
 			}
 			cwriter.close ();
 
@@ -95,7 +95,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		if (file_data == null) {
 			file_data = new FileData ();
 			file_data.filename = filename;
-			file_data.comments = new Gee.LinkedList<string>();
+			file_data.comments = new Gee.LinkedList<GComment>();
 			file_data.section_lines = new Gee.LinkedList<string>();
 			files_data[filename] = file_data;
 		}
@@ -150,6 +150,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		gcomment.symbol = symbol;
 		gcomment.returns = converter.returns;
 		gcomment.returns_annotations = returns_annotations;
+		gcomment.see_also = converter.see_also;
 
 		if (converter.brief_comment != null && short_description) {
 			var header = new Header ("@short_description", converter.brief_comment);
@@ -170,7 +171,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		}
 
 		var file_data = get_file_data (filename);
-		file_data.comments.add (create_gcomment(symbol, comment, short_description).to_string ());
+		file_data.comments.add (create_gcomment (symbol, comment, short_description));
 	}
 
 	private GComment? add_symbol (string filename, string cname, Comment? comment = null, string? symbol = null, bool title = false, bool short_description = false, string[]? returns_annotations = null) {
@@ -182,8 +183,8 @@ public class Gtkdoc.Generator : Api.Visitor {
 		file_data.section_lines.add (cname);
 
 		if (comment != null || (current_headers != null && current_headers.size > 0)) {
-			var gcomment = create_gcomment(symbol ?? cname, comment, short_description, returns_annotations);
-			file_data.comments.add (gcomment.to_string ());
+			var gcomment = create_gcomment (symbol ?? cname, comment, short_description, returns_annotations);
+			file_data.comments.add (gcomment);
 			return gcomment;
 		}
 		return null;
@@ -495,8 +496,15 @@ public class Gtkdoc.Generator : Api.Visitor {
 		if (m.is_yields) {
 			add_custom_header ("_callback_", "callback to call when the request is satisfied", {"scope async"});
 			add_custom_header ("user_data", "the data to pass to callback function", {"closure"});
+			var gcomment = add_symbol (m.get_filename(), m.get_cname (), m.documentation);
+			gcomment.returns = null; // async method has no return value
+			var see_also = gcomment.see_also; // vala bug
+			see_also += get_docbook_link (m, false, true);
+			gcomment.see_also = see_also;
+		} else {
+			add_symbol (m.get_filename(), m.get_cname (), m.documentation, null, false, false, annotations);
 		}
-		add_symbol (m.get_filename(), m.get_cname (), m.documentation, null, false, false, annotations);
+
 		if (current_dbus_interface != null && m.is_dbus_visible && !m.is_constructor) {
 			if (m.return_type != null && m.return_type.data_type != null) {
 				var dresult = new DBus.Parameter (m.get_dbus_result_name (), m.return_type.get_dbus_type_signature (), DBus.Parameter.Direction.OUT);
@@ -512,7 +520,18 @@ public class Gtkdoc.Generator : Api.Visitor {
 		current_dbus_member = old_dbus_member;
 
 		if (m.is_yields) {
-			add_symbol (m.get_filename(), m.get_finish_function_cname ());
+			var gcomment = add_symbol (m.get_filename(), m.get_finish_function_cname (), m.documentation);
+			var iter = gcomment.headers.iterator ();
+			while (iter.next ()) {
+				// remove parameters from _finish
+				message(iter.get().name);
+				if (iter.get().name.has_prefix ("@")) {
+					iter.remove ();
+				}
+			}
+			var see_also = gcomment.see_also; // vala bug
+			see_also += get_docbook_link (m);
+			gcomment.see_also = see_also;
 		}
 	}
 
diff --git a/src/doclets/gtkdoc/utils.vala b/src/doclets/gtkdoc/utils.vala
index 6ba4175..3d883d2 100644
--- a/src/doclets/gtkdoc/utils.vala
+++ b/src/doclets/gtkdoc/utils.vala
@@ -74,7 +74,7 @@ namespace Gtkdoc {
 		return null;
 	}
 
-	public string? get_docbook_link (Api.Item item, bool is_dbus = false) {
+	public string? get_docbook_link (Api.Item item, bool is_dbus = false, bool is_async_finish = false) {
 		if (item is Api.Method) {
 			string name;
 			string parent;
@@ -82,7 +82,11 @@ namespace Gtkdoc {
 				name = ((Api.Method)item).get_dbus_name ();
 				parent = "%s-".printf (get_dbus_interface (item.parent));
 			} else {
-				name = ((Api.Method)item).get_cname ();
+				if (!is_async_finish) {
+					name = ((Api.Method)item).get_cname ();
+				} else {
+					name = ((Api.Method)item).get_finish_function_cname ();
+				}
 				parent = "";
 			}
 			return """<link linkend="%s%s"><function>%s()</function></link>""".printf (to_docbook_id (parent), to_docbook_id (name), name);