doclets/gtkdoc: Fix parameters order

diff --git a/src/doclets/gtkdoc/commentconverter.vala b/src/doclets/gtkdoc/commentconverter.vala
index 0346776c2e97884198781cb391e8e324479e1e32..e53b8f56bb1923b0d22b4aaa6b00deb5ffd7a395 100644 (file)
--- 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 e4549fa18e0d296073b1c600a34735c4b2d9d8cf..35bc2319b3f585aaa34a666e559fca7124720c3c 100644 (file)
--- 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 b56d4ef7e98350c8dabe955d3b72c4d192e3ac8b..25359e666ac49480ef42144e3bd49574071208b5 100644 (file)
--- 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 6cf913e2634f92151a37b5619da05763d1c7d3ee..f3263dcbeb8f310ff6f4ac50e7c24b1bf5e43018 100644 (file)
--- 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;