[gimp] pdb: improve docs of deprecated functions

[Michael Natterer <mitch src gnome org>]

commit ef3edece9b6c685766bbd490cc7586facc90547c
Author: Michael Natterer <mitch gimp org>
Date:   Sun Apr 15 16:06:00 2018 +0200

    pdb: improve docs of deprecated functions
    
    Don't unconditionally overwrite all the proc's description, author
    etc.  Instead, try to preserve them and append the "Deprecated" notes
    to the help texts and generated comments.
    
    Only affects one procedure because we killed the meta info of all
    other deprecated procs so far, but now we don't have to do that any
    longer.

 app/pdb/text-layer-cmds.c   |    4 +++-
 libgimp/gimptextlayer_pdb.c |    6 ++++++
 pdb/app.pl                  |   24 +++++++++++++++++++++++-
 pdb/lib.pl                  |   22 ++++++++++++++++++----
 pdb/stddefs.pdb             |    4 ++--
 5 files changed, 52 insertions(+), 8 deletions(-)
---
diff --git a/app/pdb/text-layer-cmds.c b/app/pdb/text-layer-cmds.c
index 30e7c22..95c749e 100644
--- a/app/pdb/text-layer-cmds.c
+++ b/app/pdb/text-layer-cmds.c
@@ -2166,7 +2166,9 @@ register_text_layer_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-text-layer-set-hinting",
                                      "Enable/disable the use of hinting in a text layer.",
-                                     "This procedure enables or disables hinting on the text of a text 
layer. If you enable 'auto-hint', FreeType\'s automatic hinter will be used and hinting information from the 
font will be ignored.",
+                                     "This procedure enables or disables hinting on the text of a text 
layer. If you enable 'auto-hint', FreeType\'s automatic hinter will be used and hinting information from the 
font will be ignored.\n"
+                                     "\n"
+                                     "Deprecated: Use 'gimp-text-layer-set-hint-style' instead.",
                                      "Marcus Heese <heese cip ifi lmu de>",
                                      "Marcus Heese",
                                      "2008",
diff --git a/libgimp/gimptextlayer_pdb.c b/libgimp/gimptextlayer_pdb.c
index 5ef8af9..4634321 100644
--- a/libgimp/gimptextlayer_pdb.c
+++ b/libgimp/gimptextlayer_pdb.c
@@ -1091,6 +1091,12 @@ gimp_text_layer_get_hinting (gint32    layer_ID,
  * @hinting: Enable/disable the use of hinting on the text.
  * @autohint: Force the use of the autohinter provided through FreeType.
  *
+ * Enable/disable the use of hinting in a text layer.
+ *
+ * This procedure enables or disables hinting on the text of a text
+ * layer. If you enable 'auto-hint', FreeType\'s automatic hinter will
+ * be used and hinting information from the font will be ignored.
+ *
  * Deprecated: Use gimp_text_layer_set_hint_style() instead.
  *
  * Returns: TRUE on success.
diff --git a/pdb/app.pl b/pdb/app.pl
index 4e710a5..6abb2b5 100644
--- a/pdb/app.pl
+++ b/pdb/app.pl
@@ -585,12 +585,34 @@ sub generate {
        my @inargs = @{$proc->{inargs}} if (defined $proc->{inargs});
        my @outargs = @{$proc->{outargs}} if (defined $proc->{outargs});
 
+       my $blurb = $proc->{blurb};
        my $help = $proc->{help};
 
        my $procedure_name;
 
        local $success = 0;
 
+       if ($proc->{deprecated}) {
+            if ($proc->{deprecated} eq 'NONE') {
+               if (!$blurb) {
+                   $blurb = "Deprecated: There is no replacement for this procedure.";
+               }
+               if ($help) {
+                   $help .= "\n\n";
+               }
+               $help .= "Deprecated: There is no replacement for this procedure.";
+           }
+           else {
+               if (!$blurb) {
+                   $blurb = "Deprecated: Use '$proc->{deprecated}' instead.";
+               }
+               if ($help) {
+                   $help .= "\n\n";
+               }
+               $help .= "Deprecated: Use '$proc->{deprecated}' instead.";
+           }
+       }
+
        $help =~ s/gimp(\w+)\(\s*\)/"'gimp".canonicalize($1)."'"/ge;
 
        if ($proc->{group} eq "plug_in_compat") {
@@ -611,7 +633,7 @@ sub generate {
                                "$procedure_name");
   gimp_procedure_set_static_strings (procedure,
                                      "$procedure_name",
-                                     @{[ &quotewrap($proc->{blurb}, 2, 37) ]},
+                                     @{[ &quotewrap($blurb, 2, 37) ]},
                                      @{[ &quotewrap($help,  2, 37) ]},
                                      "$proc->{author}",
                                      "$proc->{copyright}",
diff --git a/pdb/lib.pl b/pdb/lib.pl
index 8159139..9f8fa1a 100644
--- a/pdb/lib.pl
+++ b/pdb/lib.pl
@@ -459,17 +459,31 @@ CODE
            $sincedesc = "\n *\n * Since: $proc->{since}";
        }
 
+       my $procdesc = '';
+
        if ($proc->{deprecated}) {
             if ($proc->{deprecated} eq 'NONE') {
-               $procdesc = &desc_wrap("Deprecated: There is no replacement " .
-                                       "for this procedure.");
+               if ($proc->{blurb}) {
+                   $procdesc = &desc_wrap($proc->{blurb}) . "\n *\n";
+               }
+               if ($proc->{help}) {
+                   $procdesc .= &desc_wrap($proc->{help}) . "\n *\n";
+               }
+               $procdesc .= &desc_wrap("Deprecated: There is no replacement " .
+                                       "for this procedure.");
            }
            else {
                my $underscores = $proc->{deprecated};
                $underscores =~ s/-/_/g;
 
-               $procdesc = &desc_wrap("Deprecated: " .
-                                      "Use $underscores() instead.");
+               if ($proc->{blurb}) {
+                   $procdesc = &desc_wrap($proc->{blurb}) . "\n *\n";
+               }
+               if ($proc->{help}) {
+                   $procdesc .= &desc_wrap($proc->{help}) . "\n *\n";
+               }
+               $procdesc .= &desc_wrap("Deprecated: " .
+                                       "Use $underscores() instead.");
            }
        }
        else {
diff --git a/pdb/stddefs.pdb b/pdb/stddefs.pdb
index 22c24e0..67178cf 100644
--- a/pdb/stddefs.pdb
+++ b/pdb/stddefs.pdb
@@ -167,10 +167,10 @@ sub yosh_pdb_misc {
 
 sub std_pdb_deprecated {
     if (@_) {
-        $blurb = $help = "Deprecated: Use '@_' instead.";
+        $blurb = $help = '';
         $deprecated = "@_";
     } else {
-        $blurb = $help = "Deprecated: There is no replacement for this procedure.";
+        $blurb = $help = '';
         $deprecated = "NONE";
     }
     $author = $copyright = $date = '';