doclets/gtkdoclet: Better support for signals

diff --git a/src/doclets/gtkdoc/commentconverter.vala b/src/doclets/gtkdoc/commentconverter.vala
index a2cf0e9fceb33b0706410268234ce401d24105c6..032d938834e3db2fd65a365c3fcabaf6bef53c42 100644 (file)
--- a/src/doclets/gtkdoc/commentconverter.vala
+++ b/src/doclets/gtkdoc/commentconverter.vala
@@ -83,7 +83,7 @@ public class Gtkdoc.CommentConverter : ContentVisitor {
        }
 
        public override void visit_symbol_link (SymbolLink sl) {
-               current_builder.append (get_reference (sl.symbol) ?? sl.label);
+               current_builder.append (get_creference (sl.symbol) ?? sl.label);
        }
   
        public override void visit_list (Content.List list) {
@@ -227,7 +227,7 @@ public class Gtkdoc.CommentConverter : ContentVisitor {
                        versioning.add (header);
                } else if (t is Taglets.See) {
                        var see = (Taglets.See)t;
-                       old_builder.append_printf ("\n<emphasis>See Also</emphasis>: %s\n", get_reference (see.symbol) ?? see.symbol_name);
+                       old_builder.append_printf ("\n<emphasis>See Also</emphasis>: %s\n", get_creference (see.symbol) ?? see.symbol_name);
                } else if (t is Taglets.Link) {
                        ((Taglets.Link)t).produce_content().accept (this);
                } else {

diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index 5efc7dbfa3f4a02e243e09e0660e83430741a731..4152ea7fbef9e55165394a6a1f8fd8587ab7bd94 100644 (file)
--- a/src/doclets/gtkdoc/generator.vala
+++ b/src/doclets/gtkdoc/generator.vala
@@ -37,6 +37,7 @@ public class Gtkdoc.Generator : Api.Visitor {
        private Class current_class;
        private Method current_method;
        private Delegate current_delegate;
+       private Api.Signal current_signal;
 
        public bool execute (Settings settings, Api.Tree tree) {
                tree.accept (this);
@@ -378,8 +379,19 @@ public class Gtkdoc.Generator : Api.Visitor {
        }
 
        public override void visit_signal (Api.Signal sig) {
-               add_comment (sig.get_filename(), "%s::%s".printf (current_cname, sig.get_cname ()), sig.documentation);
+               var old_headers = current_headers;
+               var old_signal = current_signal;
+               current_headers = new Gee.LinkedList<Header>();
+               current_signal = sig;
+
+               // gtkdoc maps parameters by their ordering, so let's manually add the first parameter
+               add_manual_header (to_lower_case (((Api.Node)sig.parent).name), "", null);
                sig.accept_all_children (this);
+               var name = sig.get_cname ().replace ("_", "-");
+               add_comment (sig.get_filename(), "%s::%s".printf (current_cname, name), sig.documentation);
+
+               current_headers = old_headers;
+               current_signal = old_signal;
        }
 
        public override void visit_creation_method (Api.Method m) {
@@ -447,7 +459,14 @@ public class Gtkdoc.Generator : Api.Visitor {
                        annotations += "array length=%s".printf (param.name+"_length1");
                } 
 
-               add_header (param.name, param.documentation, annotations);
+               if (param.documentation != null) {
+                       add_header (param.name, param.documentation, annotations);
+               }
+               else if (current_signal != null && param.documentation == null) {
+                       // gtkdoc writes arg0, arg1 which is ugly. As a workaround, we always add an header for them.
+                       add_manual_header (param.name, "", null);
+                       return;
+               }
                param.accept_all_children (this);
        }
 }

diff --git a/src/doclets/gtkdoc/utils.vala b/src/doclets/gtkdoc/utils.vala
index 4b853a16607f81fce56386e9035a2dc20d0e488a..55b19d2dbd1a50b544ce1ebfb4c4fa977eaf2ceb 100644 (file)
--- a/src/doclets/gtkdoc/utils.vala
+++ b/src/doclets/gtkdoc/utils.vala
@@ -34,32 +34,72 @@ namespace Gtkdoc {
                return string.joinv ("\n * ", comment.split ("\n"));
        }
 
-       private string? get_reference (Api.Node symbol) {
-               if (symbol is Api.Method) {
-                       return "%s()".printf (((Api.Method)symbol).get_cname ());
-               } else if (symbol is Api.FormalParameter) {
-                       return "@%s".printf (((Api.FormalParameter)symbol).name);
-               } else if (symbol is Api.Constant) {
-                       return "%%%s".printf (((Api.Constant)symbol).get_cname ());
-               } else if (symbol is Api.Signal) {
-                       return "::%s".printf (((Api.Signal)symbol).get_cname ());
-               } else if (symbol is Api.Class) {
-                       return "#%s".printf (((Api.Class)symbol).get_cname ());
-               } else if (symbol is Api.Struct) {
-                       return "#%s".printf (((Api.Struct)symbol).get_cname ());
-               } else if (symbol is Api.Interface) {
-                       return "#%s".printf (((Api.Interface)symbol).get_cname ());
-               } else if (symbol is Api.ErrorDomain) {
-                       return "#%s".printf (((Api.ErrorDomain)symbol).get_cname ());
-               } else if (symbol is Api.ErrorCode) {
-                       return "#%s".printf (((Api.ErrorCode)symbol).get_cname ());
-               } else if (symbol is Api.Delegate) {
-                       return "#%s".printf (((Api.Delegate)symbol).get_cname ());
-               } else if (symbol is Api.Enum) {
-                       return "#%s".printf (((Api.Enum)symbol).get_cname ());
+       public string? get_cname (Api.Item item)
+       {
+               if (item is Api.Method) {
+                       return ((Api.Method)item).get_cname ();
+               } else if (item is Api.FormalParameter) {
+                       return ((Api.FormalParameter)item).name;
+               } else if (item is Api.Constant) {
+                       return ((Api.Constant)item).get_cname ();
+               } else if (item is Api.Signal) {
+                       var name = ((Api.Signal)item).get_cname ();
+                       return name.replace ("_", "-");
+               } else if (item is Api.Class) {
+                       return ((Api.Class)item).get_cname ();
+               } else if (item is Api.Struct) {
+                       return ((Api.Struct)item).get_cname ();
+               } else if (item is Api.Interface) {
+                       return ((Api.Interface)item).get_cname ();
+               } else if (item is Api.ErrorDomain) {
+                       return ((Api.ErrorDomain)item).get_cname ();
+               } else if (item is Api.ErrorCode) {
+                       return ((Api.ErrorCode)item).get_cname ();
+               } else if (item is Api.Delegate) {
+                       return ((Api.Delegate)item).get_cname ();
+               } else if (item is Api.Enum) {
+                       return ((Api.Enum)item).get_cname ();
                }
                return null;
        }
+
+       public string? get_creference (Api.Item item) {
+               if (item is Api.Method) {
+                       return "%s()".printf (((Api.Method)item).get_cname ());
+               } else if (item is Api.FormalParameter) {
+                       return "@%s".printf (((Api.FormalParameter)item).name);
+               } else if (item is Api.Constant) {
+                       return "%%%s".printf (((Api.Constant)item).get_cname ());
+               } else if (item is Api.Signal) {
+                       var name = ((Api.Signal)item).get_cname ();
+                       name = name.replace ("_", "-");
+                       return "#%s::%s".printf (get_cname (item.parent), name);
+               } else {
+                       var cname = get_cname (item);
+                       if (cname != null) {
+                               return "#%s".printf (cname);
+                       }
+               }
+               return null;
+       }
+
+       public string to_lower_case (string camel) {
+               var builder = new StringBuilder ();
+               bool last_upper = true;
+               for (int i=0; i < camel.length; i++) {
+                       if (camel[i].isupper ()) {
+                               if (!last_upper) {
+                                       builder.append_c ('_');
+                               }
+                               builder.append_unichar (camel[i].tolower ());
+                               last_upper = true;
+                       } else {
+                               builder.append_unichar (camel[i]);
+                               last_upper = false;
+                       }
+               }
+               return builder.str;
+       }
 }