From: Philip Withnall <philip@tecnocode.co.uk>
Date: Thu, 16 Aug 2012 17:15:17 +0000 (+0200)
Subject: doclets/gtkdoc: Print a warning if gtk-doc sections will be missing a long description
X-Git-Tag: 0.37.1~3^2~151
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=83c0bfaabaeba8755760e791fe77965df3df587f;p=thirdparty%2Fvala.git

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.
---

diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index b3f7948da..3c07b318a 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);