[glibmm/glibmm-2-54] gmmproc: Write signal flags to generated documentation

[Kjell Ahlstedt <kjellahl src gnome org>]

commit fb4f669c20a534fc0f877266c0957091027253e0
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Wed Sep 13 08:51:25 2017 +0200

    gmmproc: Write signal flags to generated documentation
    
    Bug 785895

 tools/pm/Function.pm   |   11 ++++++++---
 tools/pm/GtkDefs.pm    |   34 ++++++++++++++++++++++++++++++----
 tools/pm/Output.pm     |    2 +-
 tools/pm/WrapParser.pm |   17 +++++++++++++++--
 4 files changed, 54 insertions(+), 10 deletions(-)
---
diff --git a/tools/pm/Function.pm b/tools/pm/Function.pm
index 6f84631..f962216 100644
--- a/tools/pm/Function.pm
+++ b/tools/pm/Function.pm
@@ -376,12 +376,12 @@ sub add_parameter($$$)
   return $self;
 }
 
-# $string get_refdoc_comment($existing_signal_docs)
+# $string get_refdoc_comment($existing_signal_docs, $signal_flags)
 # Generate a readable prototype for signals and merge the prototype into the
 # existing Doxygen comment block.
-sub get_refdoc_comment($$)
+sub get_refdoc_comment($$$)
 {
-  my ($self, $documentation) = @_;
+  my ($self, $documentation, $signal_flags) = @_;
 
   my $str = "  /**\n";
 
@@ -402,6 +402,11 @@ sub get_refdoc_comment($$)
   $str .= ")</tt>\n";
   $str .= "   *\n";
 
+  if ($signal_flags)
+  {
+    $str .= "   * Flags: $signal_flags\n   *\n";
+  }
+
   if($documentation ne "")
   {
     # Remove the initial '/** ' from the existing docs and merge it.
diff --git a/tools/pm/GtkDefs.pm b/tools/pm/GtkDefs.pm
index f1234f8..c50af4a 100644
--- a/tools/pm/GtkDefs.pm
+++ b/tools/pm/GtkDefs.pm
@@ -713,8 +713,9 @@ BEGIN { @GtkDefs::Signal::ISA=qw(GtkDefs::Function); }
 #
 #       string rettype;
 #
-#       string when. e.g. first, last, or both.
+#       string flags. e.g. Run Last, No Hooks
 #       string entity_type. e.g. vfunc or signal
+#       bool detailed; # optional
 #       bool deprecated; # optional
 #    }
 
@@ -741,7 +742,7 @@ sub new
   $$self{rettype} = "none";
   $$self{param_types} = [];
   $$self{param_names} = [];
-  $$self{when} = "";
+  $$self{flags} = "";
   $$self{class} = "";
 
   # snarf down lisp fields
@@ -760,9 +761,26 @@ sub new
     $$self{rettype} =~ s/-/ /g; #e.g. replace const-gchar* with const gchar*. Otherwise it will be used in 
code.
   }
 
-  if($def =~ s/\(when "(\S+)"\)//)
+  if ($def =~ s/\(flags "(.*?)"\)//)
   {
-    $$self{when} = $1;
+    $$self{flags} = $1;
+  }
+  elsif ($def =~ s/\(when "(\S+)"\)//)
+  {
+    # "when" is a deprecated alternative to "flags".
+    # when eq "none", "first", "last", or "both".
+    if ($1 eq "first")
+    {
+      $$self{flags} = "Run First";
+    }
+    elsif ($1 eq "last")
+    {
+      $$self{flags} = "Run Last";
+    }
+    elsif ($1 eq "both")
+    {
+      $$self{flags} = "Run First, Run Last";
+    }
   }
 
   if($$self{rettype} eq "none")
@@ -770,6 +788,7 @@ sub new
     $$self{rettype} = "void"
   }
 
+  $$self{detailed} = ($1 eq "#t") if ($def =~ s/\(detailed (\S+)\)//);
   $$self{deprecated} = ($1 eq "#t") if ($def =~ s/\(deprecated (\S+)\)//);
 
   # signals always have a parameter
@@ -790,6 +809,13 @@ sub new
   return $self;
 }
 
+# bool get_detailed()
+sub get_detailed($)
+{
+  my ($self) = @_;
+  return $$self{detailed}; # undef, 0 or 1
+}
+
 # bool get_deprecated()
 sub get_deprecated($)
 {
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index 65d37ca..80ebfc1 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -630,7 +630,7 @@ sub output_wrap_sig_decl($$$$$$$$$$$$$$)
 
   # Create a merged Doxygen comment block for the signal from the looked up
   # docs (the block will also contain a prototype of the slot as an example).
-  my $doxycomment = $objCppfunc->get_refdoc_comment($documentation);
+  my $doxycomment = $objCppfunc->get_refdoc_comment($documentation, $$objCSignal{flags});
 
   # If there was already a previous doxygen comment, we want to merge this
   # one with the previous so it is one big comment. If
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index 0e95c8f..cb3337a 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -1662,7 +1662,7 @@ sub output_wrap_signal($$$$$$$$$$$$$$$$$)
     $objCSignal = GtkDefs::lookup_signal($$self{c_class}, $signal_name);
 
     # Check for failed lookup.
-    if($objCSignal eq 0)
+    if (!$objCSignal)
     {
       print STDERR "$signal_name\n";
         $objOutputter->output_wrap_failed($signal_name,
@@ -1671,6 +1671,19 @@ sub output_wrap_signal($$$$$$$$$$$$$$$$$)
     }
   }
 
+  # Check detailed.
+  my $defs_detailed = $objCSignal->get_detailed();
+    if ($defs_detailed && !$detail_name)
+  {
+    print STDERR "Warning, $main::source: The $signal_name signal" .
+      " is marked 'detailed' in the .defs file, but not in _WRAP_SIGNAL.\n";
+  }
+  elsif (!$defs_detailed && $detail_name)
+  {
+    print STDERR "Warning, $main::source: The $signal_name signal" .
+      " is marked 'detailed' in _WRAP_SIGNAL, but not in the .defs file.\n";
+  }
+
   Output::check_deprecation($$self{deprecated}, $objCSignal->get_deprecated(),
     $deprecated, $signal_name, "signal", "SIGNAL");
 
@@ -1679,7 +1692,7 @@ sub output_wrap_signal($$$$$$$$$$$$$$$$$)
     $deprecated, $deprecation_docs, $newin, $exceptionHandler,
     $detail_name, $bTwoSignalMethods);
 
-  if($bNoDefaultHandler eq 0)
+  if (!$bNoDefaultHandler)
   {
     $objOutputter->output_wrap_default_signal_handler_h($filename, $line_num,
       $objCppSignal, $objCSignal, $ifdef, $deprecated, $exceptionHandler);