dallasgroot/Gimp
dallasgroot/Gimp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

app, libgimp, pdb: further improve function documentation.

Browse source 
- Consistently add the text about inserting items into the image after
  creation, with correct function links/references.
- Consistent grammar for function blurb.
- Make @name argument nullable for gimp_path_new().
This commit is contained in:
Jehan 2025-10-11 21:56:53 +02:00
parent 51e9135c58
commit a46d0c3117
12 changed files with 81 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
app/pdb/channel-cmds.c
View file

@ -450,7 +450,10 @@ register_channel_procs (GimpPDB *pdb)
gimp_procedure_set_static_help (procedure,
"Create a new channel from a color component",
"This procedure creates a new channel from a color component.\n"
"The new channel still needs to be added to the image, as this is not automatic. Add the new channel with 'gimp-image-insert-channel'. Other attributes, such as channel visibility, should be set with explicit procedure calls.",
"\n"
"The new channel still needs to be added to the image, as this is not automatic. Add the new channel with [method@Gimp.Image.insert_channel].\n"
"\n"
"Other attributes, such as channel visibility, should be set with explicit procedure calls.",
NULL);
gimp_procedure_set_static_attribution (procedure,
"Shlomi Fish <shlomif@iglu.org.il>",
@ -494,7 +497,8 @@ register_channel_procs (GimpPDB *pdb)
gimp_procedure_set_static_help (procedure,
"Copy a channel.",
"This procedure copies the specified channel and returns the copy.\n"
"The new channel still needs to be added to the image, as this is not automatic. Add the new channel with 'gimp-image-insert-channel'.",
"\n"
"The new channel still needs to be added to the image, as this is not automatic. Add the new channel with [method@Gimp.Image.insert_channel].",
NULL);
gimp_procedure_set_static_attribution (procedure,
"Spencer Kimball & Peter Mattis",

2
app/pdb/link-layer-cmds.c
View file

@ -254,7 +254,7 @@ register_link_layer_procs (GimpPDB *pdb)
gimp_object_set_static_name (GIMP_OBJECT (procedure),
"gimp-link-layer-new");
gimp_procedure_set_static_help (procedure,
"Creates a new link layer.",
"Create a new link layer.",
"This procedure creates a link layer monitoring the specified @file.\n"
"\n"
"The new layer still needs to be added to the image as this is not automatic. Add the new layer with the [method@Image.insert_layer] method.\n"

18
app/pdb/path-cmds.c
View file

@ -1144,8 +1144,10 @@ register_path_procs (GimpPDB *pdb)
gimp_object_set_static_name (GIMP_OBJECT (procedure),
"gimp-path-new");
gimp_procedure_set_static_help (procedure,
"Creates a new empty path object.",
"Creates a new empty path object. The path object needs to be added to the image using 'gimp-image-insert-path'.",
"Create a new empty path object.",
"This procedure creates a new empty path object. If @name is %NULL, a default path name will be used.\n"
"\n"
"The new path still needs to be added to the image as this is not automatic. Add the new path with the [method@Image.insert_path] method.",
NULL);
gimp_procedure_set_static_attribution (procedure,
"Simon Budig",
@ -1161,7 +1163,7 @@ register_path_procs (GimpPDB *pdb)
gimp_param_spec_string ("name",
"name",
"the name of the new path object.",
FALSE, FALSE, FALSE,
FALSE, TRUE, FALSE,
NULL,
GIMP_PARAM_READWRITE));
gimp_procedure_add_return_value (procedure,
@ -1180,8 +1182,10 @@ register_path_procs (GimpPDB *pdb)
gimp_object_set_static_name (GIMP_OBJECT (procedure),
"gimp-path-new-from-text-layer");
gimp_procedure_set_static_help (procedure,
"Creates a new path object from a text layer.",
"Creates a new path object from a text layer. The path object needs to be added to the image using 'gimp-image-insert-path'.",
"Create a new path object from a text layer.",
"This procedure creates a new path object from a text layer.\n"
"\n"
"The new path still needs to be added to the image as this is not automatic. Add the new path with the [method@Image.insert_path] method.",
NULL);
gimp_procedure_set_static_attribution (procedure,
"Marcus Heese <heese@cip.ifi.lmu.de>",
@ -1216,7 +1220,9 @@ register_path_procs (GimpPDB *pdb)
"gimp-path-copy");
gimp_procedure_set_static_help (procedure,
"Copy a path object.",
"This procedure copies the specified path object and returns the copy.",
"This procedure copies the specified path object and returns the copy.\n"
"\n"
"The new path still needs to be added to the image as this is not automatic. Add the new path with the [method@Image.insert_path] method.",
NULL);
gimp_procedure_set_static_attribution (procedure,
"Barak Itkin <lightningismyname@gmail.com>",

4
app/pdb/vector-layer-cmds.c
View file

@ -974,8 +974,8 @@ register_vector_layer_procs (GimpPDB *pdb)
gimp_object_set_static_name (GIMP_OBJECT (procedure),
"gimp-vector-layer-new");
gimp_procedure_set_static_help (procedure,
"Creates a new vector layer.",
"This procedure creates a new path layer displaying the specified @path. By default, the fill and stroke properties will be defined by the context.\n"
"Create a new vector layer.",
"This procedure creates a new vector layer displaying the specified @path. By default, the fill and stroke properties will be defined by the context.\n"
"\n"
"The new layer still needs to be added to the image as this is not automatic. Add the new layer with the [method@Image.insert_layer] method.\n"
"\n"

9
libgimp/gimpchannel_pdb.c
View file

@ -104,8 +104,11 @@ gimp_channel_new (GimpImage *image,
* Create a new channel from a color component
*
* This procedure creates a new channel from a color component.
*
* The new channel still needs to be added to the image, as this is not
* automatic. Add the new channel with gimp_image_insert_channel().
* automatic. Add the new channel with
* [method@Gimp.Image.insert_channel].
*
* Other attributes, such as channel visibility, should be set with
* explicit procedure calls.
*
@ -148,8 +151,10 @@ gimp_channel_new_from_component (GimpImage *image,
* Copy a channel.
*
* This procedure copies the specified channel and returns the copy.
*
* The new channel still needs to be added to the image, as this is not
* automatic. Add the new channel with gimp_image_insert_channel().
* automatic. Add the new channel with
* [method@Gimp.Image.insert_channel].
*
* Returns: (transfer none): The newly copied channel.
**/

2
libgimp/gimplinklayer_pdb.c
View file

@ -41,7 +41,7 @@
* @image: The image.
* @file: The file this link layer will monitor.
*
* Creates a new link layer.
* Create a new link layer.
*
* This procedure creates a link layer monitoring the specified @file.
*

25
libgimp/gimppath_pdb.c
View file

@ -39,12 +39,16 @@
/**
* gimp_path_new:
* @image: The image.
* @name: the name of the new path object.
* @name: (nullable): the name of the new path object.
*
* Creates a new empty path object.
* Create a new empty path object.
*
* Creates a new empty path object. The path object needs to be added
* to the image using gimp_image_insert_path().
* This procedure creates a new empty path object. If @name is %NULL, a
* default path name will be used.
*
* The new path still needs to be added to the image as this is not
* automatic. Add the new path with the [method@Image.insert_path]
* method.
*
* Returns: (transfer none):
* the current path object, 0 if no path exists in the image.
@ -82,10 +86,13 @@ gimp_path_new (GimpImage *image,
* @image: The image.
* @layer: The text layer.
*
* Creates a new path object from a text layer.
* Create a new path object from a text layer.
*
* Creates a new path object from a text layer. The path object needs
* to be added to the image using gimp_image_insert_path().
* This procedure creates a new path object from a text layer.
*
* The new path still needs to be added to the image as this is not
* automatic. Add the new path with the [method@Image.insert_path]
* method.
*
* Returns: (transfer none): The path of the text layer.
*
@ -126,6 +133,10 @@ gimp_path_new_from_text_layer (GimpImage *image,
* This procedure copies the specified path object and returns the
* copy.
*
* The new path still needs to be added to the image as this is not
* automatic. Add the new path with the [method@Image.insert_path]
* method.
*
* Returns: (transfer none): The newly copied path object.
*
* Since: 2.6

4
libgimp/gimpvectorlayer_pdb.c
View file

@ -41,9 +41,9 @@
* @image: The image.
* @path: The path to create the layer from.
*
* Creates a new vector layer.
* Create a new vector layer.
*
* This procedure creates a new path layer displaying the specified
* This procedure creates a new vector layer displaying the specified
* @path. By default, the fill and stroke properties will be defined by
* the context.
*

12
pdb/groups/channel.pdb
View file

@ -77,8 +77,9 @@ sub channel_copy {
$help = <<'HELP';
This procedure copies the specified channel and returns the copy.
The new channel still needs to be added to the image, as this is not
automatic. Add the new channel with gimp_image_insert_channel().
automatic. Add the new channel with [method@Gimp.Image.insert_channel].
HELP
&std_pdb_misc;
@ -160,10 +161,13 @@ sub channel_new_from_component {
$help = <<'HELP';
This procedure creates a new channel from a color component.
The new channel still needs to be added to the image, as this is not
automatic. Add the new channel with gimp_image_insert_channel(). Other
attributes, such as channel visibility, should be set with explicit
procedure calls.
automatic. Add the new channel with [method@Gimp.Image.insert_channel].
Other attributes, such as channel visibility, should be set with
explicit procedure calls.
HELP
&shlomi_pdb_misc('2005', '2.4');

2
pdb/groups/link_layer.pdb
View file

@ -19,7 +19,7 @@
sub link_layer_new {
$blurb = 'Creates a new link layer.';
$blurb = 'Create a new link layer.';
$help = <<'HELP';
This procedure creates a link layer monitoring the specified @file.

28
pdb/groups/path.pdb
View file

@ -15,11 +15,16 @@
# along with this program. If not, see <https://www.gnu.org/licenses/>.
sub path_new {
$blurb = 'Creates a new empty path object.';
$blurb = 'Create a new empty path object.';
$help = <<'HELP';
Creates a new empty path object. The path object needs to be added to
the image using gimp_image_insert_path().
This procedure creates a new empty path object.
If @name is %NULL, a default path name will be used.
The new path still needs to be added to the image as this is not
automatic. Add the new path with the [method@Image.insert_path]
method.
HELP
&simon_pdb_misc('2005', '2.4');
@ -27,7 +32,7 @@ HELP
@inargs = (
{ name => 'image', type => 'image',
desc => 'The image' },
{ name => 'name', type => 'string',
{ name => 'name', type => 'string', none_ok => 1,
desc => 'the name of the new path object.' }
);
@ -47,11 +52,15 @@ CODE
}
sub path_new_from_text_layer {
$blurb = 'Creates a new path object from a text layer.';
$blurb = 'Create a new path object from a text layer.';
$help = <<'HELP';
Creates a new path object from a text layer. The path object needs to
be added to the image using gimp_image_insert_path().
This procedure creates a new path object from a text layer.
The new path still needs to be added to the image as this is not
automatic. Add the new path with the [method@Image.insert_path]
method.
HELP
&marcus_pdb_misc('2008', '2.6');
@ -95,6 +104,11 @@ sub path_copy {
$help = <<'HELP';
This procedure copies the specified path object and returns the copy.
The new path still needs to be added to the image as this is not
automatic. Add the new path with the [method@Image.insert_path]
method.
HELP
barak_pdb_misc('2008', '2.6');

4
pdb/groups/vector_layer.pdb
View file

@ -18,10 +18,10 @@
sub vector_layer_new {
$blurb = 'Creates a new vector layer.';
$blurb = 'Create a new vector layer.';
$help = <<'HELP';
This procedure creates a new path layer displaying the specified @path. By
This procedure creates a new vector layer displaying the specified @path. By
default, the fill and stroke properties will be defined by the context.