[valadoc] doclets/gtkdoc: Print a warning if gtk-doc sections will be missing a long description

[Florian Brosch <flobrosch src gnome org>]

commit 83c0bfaabaeba8755760e791fe77965df3df587f
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Aug 16 19:15:17 2012 +0200

    doclets/gtkdoc: Print a warning if gtk-doc sections will be missing a long description
    
    If a Valadoc comment is used as the description for a gtk-doc section,
    gtk-doc will emit a warning if only a short description is provided.
    This pseudo-forwards that warning to the Valadoc output (from the
    *-undocumented.txt file) so it doesnât get lost.

 src/doclets/gtkdoc/generator.vala |   16 ++++++++++++----
 1 files changed, 12 insertions(+), 4 deletions(-)
---
diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index b3f7948..3c07b31 100644
--- a/src/doclets/gtkdoc/generator.vala
+++ b/src/doclets/gtkdoc/generator.vala
@@ -204,7 +204,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		return headers;
 	}
 
-	private void set_section_comment (string filename, string section_name, Content.Comment? comment) {
+	private void set_section_comment (string filename, string section_name, Content.Comment? comment, string symbol_full_name) {
 		var file_data = get_file_data (filename);
 		if (file_data.title == null) {
 			file_data.title = section_name;
@@ -221,6 +221,14 @@ public class Gtkdoc.Generator : Api.Visitor {
 		gcomment.is_section = true;
 		gcomment.short_description = true;
 		file_data.section_comment = gcomment;
+
+		/* gtk-doc will warn about missing long descriptions (e.g.
+		 * âalias-details:Long_Descriptionâ in *-undocumented.txt), so
+		 * forward that as a Valadoc warning so that it doesnât get lost
+		 * in the gtk-doc output files. */
+		if (gcomment.long_comment == null || gcomment.long_comment == "") {
+			reporter.simple_warning ("Missing long description in the documentation for â%sâ which forms gtk-doc section â%sâ.", symbol_full_name, section_name);
+		}
 	}
 
 	private GComment create_gcomment (string symbol, Content.Comment? comment, string[]? returns_annotations = null, bool is_dbus = false) {
@@ -323,7 +331,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 
 	public override void visit_namespace (Api.Namespace ns) {
 		if (ns.get_filename () != null && ns.documentation != null) {
-			set_section_comment (ns.get_filename (), get_section (ns.get_filename ()), ns.documentation);
+			set_section_comment (ns.get_filename (), get_section (ns.get_filename ()), ns.documentation, ns.get_full_name ());
 		}
 
 		ns.accept_all_children (this);
@@ -344,7 +352,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		iface.accept_all_children (this);
 
 		add_symbol (iface.get_filename(), iface.get_cname(), iface.documentation, null);
-		set_section_comment (iface.get_filename(), iface.get_cname(), iface.documentation);
+		set_section_comment (iface.get_filename(), iface.get_cname(), iface.documentation, iface.get_full_name ());
 
 		if (current_dbus_interface != null) {
 			current_dbus_interface.write (settings, reporter);
@@ -408,7 +416,7 @@ public class Gtkdoc.Generator : Api.Visitor {
 		cl.accept_all_children (this);
 
 		add_symbol (cl.get_filename(), cl.get_cname(), cl.documentation, null);
-		set_section_comment (cl.get_filename(), cl.get_cname(), cl.documentation);
+		set_section_comment (cl.get_filename(), cl.get_cname(), cl.documentation, cl.get_full_name ());
 
 		if (current_dbus_interface != null) {
 			current_dbus_interface.write (settings, reporter);