[valadoc] doclets/gtkdoclet: Better support for signals

[Florian Brosch <flobrosch src gnome org>]

commit fc79d730f7b7aa65b704dbe7896e4067c16e3998
Author: Luca Bruno <lethalman88 gmail com>
Date:   Tue May 4 22:02:51 2010 +0200

    doclets/gtkdoclet: Better support for signals

 src/doclets/gtkdoc/commentconverter.vala |    4 +-
 src/doclets/gtkdoc/generator.vala        |   23 +++++++-
 src/doclets/gtkdoc/utils.vala            |   86 ++++++++++++++++++++++--------
 3 files changed, 86 insertions(+), 27 deletions(-)
---
diff --git a/src/doclets/gtkdoc/commentconverter.vala b/src/doclets/gtkdoc/commentconverter.vala
index a2cf0e9..032d938 100644
--- 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 5efc7db..4152ea7 100644
--- 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 4b853a1..55b19d2 100644
--- 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;
+	}
 }