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.
This commit is contained in:
Michael Natterer 2018-04-15 16:06:00 +02:00
parent 50536e1c38
commit ef3edece9b
5 changed files with 52 additions and 8 deletions

View File

@ -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",

View File

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

View File

@ -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}",

View File

@ -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 {

View File

@ -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 = '';