GNOME.org
 

[valadoc] doclets/gtkdoc: Fix parameters order

commit 2dbcfaabcecdd543a35d8e535453f780583297d0
Author: Luca Bruno <lethalman88 gmail com>
Date:   Fri Aug 20 02:15:21 2010 +0200

    doclets/gtkdoc: Fix parameters order

 src/doclets/gtkdoc/commentconverter.vala |   28 ++++----
 src/doclets/gtkdoc/gcomment.vala         |   35 ++++++++++-
 src/doclets/gtkdoc/generator.vala        |  100 +++++++++++++++---------------
 src/doclets/gtkdoc/utils.vala            |   11 +++
 4 files changed, 106 insertions(+), 68 deletions(-)
---
diff --git a/src/doclets/gtkdoc/commentconverter.vala b/src/doclets/gtkdoc/commentconverter.vala
index 0346776..e53b8f5 100644
--- a/src/doclets/gtkdoc/commentconverter.vala
+++ b/src/doclets/gtkdoc/commentconverter.vala
@@ -24,29 +24,24 @@ using Valadoc;
 using Valadoc.Api;
 using Valadoc.Content;
 
-public class Gtkdoc.Header {
-	public string name;
-	public string[]? annotations;
-	public string? value;
-
-	public Header (string name, string? value = null) {
-		this.name = name;
-		this.value = value;
-	}
-}
-
 public class Gtkdoc.CommentConverter : ContentVisitor {
+	public Api.Node node_reference;
+
 	public bool is_dbus;
 	public string brief_comment;
 	public string long_comment;
 	public string returns;
-	public Gee.List<Header> headers = new Gee.LinkedList<Header> ();
+	public Gee.List<Header> parameters = 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;
 
+	public CommentConverter (Api.Node? node_reference = null) {
+		this.node_reference = node_reference;
+	}
+
 	public void convert (Comment comment, bool is_dbus = false) {
 		this.is_dbus = is_dbus;
 		comment.accept (this);
@@ -227,8 +222,13 @@ public class Gtkdoc.CommentConverter : ContentVisitor {
 
 		t.accept_children (this);
 		if (t is Taglets.Param) {
-			var header = new Header ("@"+((Taglets.Param)t).parameter_name, current_builder.str);
-			headers.add (header);
+			double pos = double.MAX;
+			var param_name = ((Taglets.Param)t).parameter_name;
+			if (node_reference != null) {
+				pos = get_parameter_pos (node_reference, param_name);
+			}
+			var header = new Header (param_name, current_builder.str, pos);
+			parameters.add (header);
 		} else if (t is Taglets.InheritDoc) {
 			((Taglets.InheritDoc)t).produce_content().accept (this);
 		} else if (t is Taglets.Return) {
diff --git a/src/doclets/gtkdoc/gcomment.vala b/src/doclets/gtkdoc/gcomment.vala
index e4549fa..35bc231 100644
--- a/src/doclets/gtkdoc/gcomment.vala
+++ b/src/doclets/gtkdoc/gcomment.vala
@@ -20,10 +20,33 @@
 * 	Luca Bruno <lethalman88 gmail com>
 */
 
+public class Gtkdoc.Header {
+	public string name;
+	public string[]? annotations;
+	public string? value;
+	public double pos;
+
+	public Header (string name, string? value = null, double pos = double.MAX) {
+		this.name = name;
+		this.value = value;
+		this.pos = pos;
+	}
+
+	public int cmp (Header header) {
+		if (pos > header.pos) {
+			return 1;
+		} else if (pos < header.pos) {
+			return -1;
+		}
+		return 0;
+	}
+}
+
 public class Gtkdoc.GComment {
 	public string symbol;
 	public string[] symbol_annotations;
 	public Gee.List<Header> headers = new Gee.LinkedList<Header> ();
+	public bool short_description;
 	public string brief_comment;
 	public string long_comment;
 	public string returns;
@@ -42,8 +65,13 @@ public class Gtkdoc.GComment {
 			}
 		}
 
+		if (short_description && brief_comment != null) {
+			builder.append_printf ("\n * @short_description: %s", commentize (brief_comment));
+		}
+
+		headers.sort ((CompareFunc) Header.cmp);
 		foreach (var header in headers) {
-			builder.append_printf ("\n * %s:", header.name);
+			builder.append_printf ("\n * @%s:", header.name);
 			if (header.annotations != null && header.annotations.length > 0) {
 				foreach (var annotation in header.annotations) {
 					builder.append_printf (" (%s)", annotation);
@@ -57,7 +85,7 @@ public class Gtkdoc.GComment {
 			}
 		}
 
-		if (brief_comment != null) {
+		if (!short_description && brief_comment != null) {
 			builder.append_printf  ("\n * \n * %s", commentize (brief_comment));
 		}
 		if (long_comment != null) {
@@ -137,12 +165,13 @@ public class Gtkdoc.GComment {
 			builder.append (long_comment);
 		}
 
+		headers.sort ((CompareFunc) Header.cmp);
 		if (headers.size > 0 || returns != null) {
 			builder.append ("""<variablelist role="params">""");
 			foreach (var header in headers) {
 				builder.append_printf ("""<varlistentry><term><parameter>%s</parameter>&#160;:</term>
 <listitem><simpara> %s </simpara></listitem></varlistentry>""",
-									   header.name.offset (1), header.value);
+									   header.name, header.value);
 			}
 			if (returns != null) {
 				builder.append_printf ("""<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term>
diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index b56d4ef..25359e6 100644
--- a/src/doclets/gtkdoc/generator.vala
+++ b/src/doclets/gtkdoc/generator.vala
@@ -46,6 +46,17 @@ public class Gtkdoc.Generator : Api.Visitor {
 	private DBus.Interface current_dbus_interface;
 	private DBus.Member current_dbus_member;
 
+	private Api.Node? current_method_or_delegate {
+		get {
+			if (current_method != null) {
+				return current_method;
+			} else if (current_delegate != null) {
+				return current_delegate;
+			}
+			return null;
+		}
+	}
+
 	public bool execute (Settings settings, Api.Tree tree) {
 		this.settings = settings;
 		tree.accept (this);
@@ -166,15 +177,13 @@ public class Gtkdoc.Generator : Api.Visitor {
 		}
 
 		var gcomment = create_gcomment ("SECTION:%s".printf (get_section (filename)), comment);
-		if (gcomment.brief_comment != null) {
-			gcomment.headers.insert (0, new Header ("@short_description", gcomment.brief_comment));
-			gcomment.brief_comment = null;
-		}
+		gcomment.short_description = true;
 		file_data.section_comment = gcomment;
 	}
 
 	private GComment create_gcomment (string symbol, Comment? comment, string[]? returns_annotations = null, bool is_dbus = false) {
-		var converter = new Gtkdoc.CommentConverter ();
+		var converter = new Gtkdoc.CommentConverter (current_method_or_delegate);
+
 		if (comment != null) {
 			converter.convert (comment, is_dbus);
 		}
@@ -188,7 +197,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		gcomment.brief_comment = converter.brief_comment;
 		gcomment.long_comment = converter.long_comment;
 
-		gcomment.headers.add_all (merge_headers (converter.headers, current_headers));
+		gcomment.headers.add_all (merge_headers (converter.parameters, current_headers));
 		gcomment.versioning.add_all (converter.versioning);
 		return gcomment;
 	}
@@ -210,37 +219,37 @@ public class Gtkdoc.Generator : Api.Visitor {
 		return gcomment;
 	}
 
-	private Header? add_custom_header (string name, string? comment, string[]? annotations = null) {
+	private Header? add_custom_header (string name, string? comment, string[]? annotations = null, double pos = double.MAX) {
 		if (comment == null && annotations == null) {
 			return null;
 		}
 
-		var header = new Header ("@"+name);
+		var header = new Header (name, comment, pos);
 		header.annotations = annotations;
-		header.value = comment;
 		current_headers.add (header);
 		return header;
 	}
 
-	private void remove_custom_header (string name) {
-		var header_name = "@%s".printf (name);
+	private Header? remove_custom_header (string name) {
 		var it = current_headers.iterator();
 		while (it.next ()) {
 			var header = it  get ();
-			if (header.name == header_name) {
+			if (header.name == name) {
 				it.remove ();
-				break;
+				return header;
 			}
 		}
+		return null;
 	}
 
-	private Header? add_header (string name, Comment? comment, string[]? annotations = null) {
+	private Header? add_header (string name, Comment? comment, string[]? annotations = null, double pos = double.MAX) {
 		if (comment == null && annotations == null) {
 			return null;
 		}
 
-		var converter = new Gtkdoc.CommentConverter ();
-		var header = new Header ("@"+name);
+		var converter = new Gtkdoc.CommentConverter (current_method_or_delegate);
+		var header = new Header (name);
+		header.pos = pos;
 
 		if (comment != null) {
 			converter.convert (comment);
@@ -363,7 +372,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 	}
 
 	public override void visit_error_domain (Api.ErrorDomain edomain) {
-		if (current_method != null || current_delegate != null) {
+		if (current_method_or_delegate != null) {
 			// method throws error
 			Header? param_header = null;
 			foreach (var header in current_headers) {
@@ -373,7 +382,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 				}
 			}
 			if (param_header == null) {
-				add_custom_header ("error", "location to store the error occuring, or %NULL to ignore", {"error-domains %s".printf (edomain.get_cname ())});
+				add_custom_header ("error", "location to store the error occuring, or %NULL to ignore", {"error-domains %s".printf (edomain.get_cname ())}, double.MAX-1);
 			} else {
 				// assume the only annotation is error-domains
 				var annotation = param_header.annotations[0];
@@ -422,14 +431,14 @@ public class Gtkdoc.Generator : Api.Visitor {
 
 		if (prop.getter != null && !prop.getter.is_private && prop.getter.is_get) {
 			var gcomment = add_symbol (prop.get_filename(), prop.getter.get_cname ());
-			gcomment.headers.add (new Header ("@self", "the %s instance to query".printf (get_docbook_link (prop.parent))));
+			gcomment.headers.add (new Header ("self", "the %s instance to query".printf (get_docbook_link (prop.parent)), 1));
 			gcomment.returns = "the value of the %s property".printf (get_docbook_link (prop));
 		}
 
 		if (prop.setter != null && !prop.setter.is_private && prop.setter.is_set) {
 			var gcomment = add_symbol (prop.get_filename(), prop.setter.get_cname ());
-			gcomment.headers.insert (0, new Header ("@self", "the %s instance to modify".printf (get_docbook_link (prop.parent))));
-			gcomment.headers.add (new Header ("@value", "the new value of the %s property".printf (get_docbook_link (prop))));
+			gcomment.headers.add (new Header ("self", "the %s instance to modify".printf (get_docbook_link (prop.parent)), 1));
+			gcomment.headers.add (new Header ("value", "the new value of the %s property".printf (get_docbook_link (prop)), 2));
 		}
 	}
 
@@ -482,8 +491,8 @@ public class Gtkdoc.Generator : Api.Visitor {
 		var name = sig.get_cname().replace ("_", "-");
 		var gcomment = add_comment (sig.get_filename(), "%s::%s".printf (current_cname, name), sig.documentation);
 		// gtkdoc maps parameters by their ordering, so let's customly add the first parameter
-		gcomment.headers.insert (0, new Header ("@%s".printf (to_lower_case (((Api.Node)sig.parent).name)),
-												"the %s instance that received the signal".printf (get_docbook_link (sig.parent))));
+		gcomment.headers.insert (0, new Header (to_lower_case (((Api.Node)sig.parent).name),
+												   "the %s instance that received the signal".printf (get_docbook_link (sig.parent)), 0.1));
 		if (current_dbus_interface != null && sig.is_dbus_visible) {
 			var dbuscomment = create_gcomment (sig.get_dbus_name (), sig.documentation, null, true);
 			current_dbus_member.comment = dbuscomment;
@@ -523,6 +532,10 @@ public class Gtkdoc.Generator : Api.Visitor {
 			current_dbus_member = new DBus.Member (m.get_dbus_name ());
 		}
 
+		if (!m.is_static && !m.is_constructor) {
+			add_custom_header ("self", "the %s instance".printf (get_docbook_link (m.parent)), null, 0.1);
+		}
+
 		m.accept_all_children (this);
 
 		Header error_header = null;
@@ -530,19 +543,10 @@ 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"});
-			gcomment = add_symbol (m.get_filename(), m.get_cname (), m.documentation);
-
 			// remove error from here, put that in the _finish function
-			var it = gcomment.headers.iterator ();
-			while (it.next ()) {
-				var header = it.get ();
-				if (header.name == "@error") {
-					error_header = header;
-					it.remove ();
-					break;
-				}
-			}
+			error_header = remove_custom_header ("error");
 
+			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);
@@ -551,9 +555,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 			gcomment = add_symbol (m.get_filename(), m.get_cname (), m.documentation, null, annotations);
 		}
 
-		if (!m.is_static && !m.is_constructor) {
-			gcomment.headers.insert (0, new Header ("@self", "the %s instance".printf (get_docbook_link (m.parent))));
-		}
+		remove_custom_header ("self");
 
 		if (current_dbus_interface != null && m.is_dbus_visible && !m.is_constructor) {
 			if (m.return_type != null && m.return_type.data_type != null) {
@@ -571,19 +573,12 @@ public class Gtkdoc.Generator : Api.Visitor {
 
 		if (m.is_yields) {
 			var finish_gcomment = add_symbol (m.get_filename(), m.get_finish_function_cname (), m.documentation);
-
-			var iter = finish_gcomment.headers.iterator ();
-			while (iter.next ()) {
-				// remove parameters from _finish
-				if (iter.get().name.has_prefix ("@")) {
-					iter.remove ();
-				}
-			}
+			finish_gcomment.headers.clear ();
 
 			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 ("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 GAsyncResult"));
 			if (error_header != null) {
 				finish_gcomment.headers.add (error_header);
 			}
@@ -615,7 +610,8 @@ public class Gtkdoc.Generator : Api.Visitor {
 
 		if (param.parameter_type.data_type is Api.Array) {
 			annotations += "array length=%s_length1".printf (param.name);
-			add_custom_header ("%s_length1".printf (param.name), "length of the @%s array".printf (param.name));
+			add_custom_header ("%s_length1".printf (param.name), "length of the @%s array".printf (param.name),
+							   null, get_parameter_pos (current_method_or_delegate, param.name)+0.1);
 		}
 
 		if (get_cname (param.parameter_type.data_type) == "GError") {
@@ -626,12 +622,14 @@ public class Gtkdoc.Generator : Api.Visitor {
 			// gtkdoc writes arg0, arg1 which is ugly. As a workaround, we always add an header for them.
 			add_custom_header (param.name, "", null);
 		} else {
-			add_header (param.name, param.documentation, annotations);
+			add_header (param.name, param.documentation, annotations,
+						get_parameter_pos (current_method_or_delegate, param.name));
 		}
 
 		if (param.parameter_type.data_type is Api.Delegate) {
-			add_custom_header ("%s_target".printf (param.name), "user data to pass to @%s".printf (param.name), {"allow-none", "closure"});
-			add_custom_header ("%s_target_destroy_notify".printf (param.name), "function to call when @%s_target is no longer needed".printf (param.name), {"allow-none"});
+			add_custom_header ("%s_target".printf (param.name), "user data to pass to @%s".printf (param.name),
+							   {"allow-none", "closure"}, get_parameter_pos (current_method_or_delegate, param.name)+0.1);
+			add_custom_header ("%s_target_destroy_notify".printf (param.name), "function to call when @%s_target is no longer needed".printf (param.name), {"allow-none"}, get_parameter_pos (current_method_or_delegate, param.name)+0.2);
 		}
 
 		if (current_dbus_member != null) {
diff --git a/src/doclets/gtkdoc/utils.vala b/src/doclets/gtkdoc/utils.vala
index 6cf913e..f3263dc 100644
--- a/src/doclets/gtkdoc/utils.vala
+++ b/src/doclets/gtkdoc/utils.vala
@@ -128,6 +128,17 @@ namespace Gtkdoc {
 		return null;
 	}
 
+	public double get_parameter_pos (Api.Node node, string name) {
+		double pos = 1;
+		foreach (var param in node.get_children_by_type (NodeType.FORMAL_PARAMETER)) {
+			if (param.name == name) {
+				return pos;
+			}
+			pos++;
+		}
+		return -1;
+	}
+
 	public string to_lower_case (string camel) {
 		var builder = new StringBuilder ();
 		bool last_upper = true;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]