From f02a218356c7a931fbba27c784b35be822889c92 Mon Sep 17 00:00:00 2001
From: Michael Natterer <mitch@gimp.org>
Date: Wed, 31 Jul 2019 13:12:46 +0200
Subject: [PATCH] pdb, libgimp: add (out) annotations to everything returned
 via pointers

---
 libgimp/gimp_pdb.c                  |  2 +-
 libgimp/gimpbrush_pdb.c             | 26 +++++++++---------
 libgimp/gimpbrushes_pdb.c           |  2 +-
 libgimp/gimpbuffer_pdb.c            |  2 +-
 libgimp/gimpchannel_pdb.c           |  2 +-
 libgimp/gimpcontext_pdb.c           | 16 +++++------
 libgimp/gimpdrawable_pdb.c          | 42 ++++++++++++++---------------
 libgimp/gimpdrawablecolor_pdb.c     | 12 ++++-----
 libgimp/gimpdynamics_pdb.c          |  2 +-
 libgimp/gimpfileops_pdb.c           |  2 +-
 libgimp/gimpfonts_pdb.c             |  2 +-
 libgimp/gimpgimprc_pdb.c            |  4 +--
 libgimp/gimpgradient_pdb.c          | 32 +++++++++++-----------
 libgimp/gimpgradients_pdb.c         |  2 +-
 libgimp/gimpimage_pdb.c             | 28 +++++++++----------
 libgimp/gimpimagecolorprofile_pdb.c |  4 +--
 libgimp/gimpimagegrid_pdb.c         | 12 ++++-----
 libgimp/gimpimagesamplepoints_pdb.c |  2 +-
 libgimp/gimpitem_pdb.c              |  4 +--
 libgimp/gimppalette_pdb.c           | 10 +++----
 libgimp/gimppalettes_pdb.c          |  2 +-
 libgimp/gimppattern_pdb.c           | 16 +++++------
 libgimp/gimppatterns_pdb.c          |  2 +-
 libgimp/gimpproceduraldb_pdb.c      | 36 ++++++++++++-------------
 libgimp/gimpselection_pdb.c         | 10 +++----
 libgimp/gimptextlayer_pdb.c         |  4 +--
 libgimp/gimptexttool_pdb.c          |  8 +++---
 libgimp/gimpvectors_pdb.c           | 28 +++++++++----------
 pdb/lib.pl                          |  4 +--
 29 files changed, 159 insertions(+), 159 deletions(-)

diff --git a/libgimp/gimp_pdb.c b/libgimp/gimp_pdb.c
index 9b736674b3..957a5381b8 100644
--- a/libgimp/gimp_pdb.c
+++ b/libgimp/gimp_pdb.c
@@ -207,7 +207,7 @@ gimp_get_parasite (const gchar *name)
 
 /**
  * gimp_get_parasite_list:
- * @num_parasites: The number of attached parasites.
+ * @num_parasites: (out) The number of attached parasites.
  *
  * List all parasites.
  *
diff --git a/libgimp/gimpbrush_pdb.c b/libgimp/gimpbrush_pdb.c
index c40c6122e4..f6d032ef2c 100644
--- a/libgimp/gimpbrush_pdb.c
+++ b/libgimp/gimpbrush_pdb.c
@@ -253,10 +253,10 @@ gimp_brush_is_editable (const gchar *name)
 /**
  * gimp_brush_get_info:
  * @name: The brush name.
- * @width: The brush width.
- * @height: The brush height.
- * @mask_bpp: The brush mask bpp.
- * @color_bpp: The brush color bpp.
+ * @width: (out) The brush width.
+ * @height: (out) The brush height.
+ * @mask_bpp: (out) The brush mask bpp.
+ * @color_bpp: (out) The brush color bpp.
  *
  * Retrieves information about the specified brush.
  *
@@ -309,14 +309,14 @@ gimp_brush_get_info (const gchar *name,
 /**
  * gimp_brush_get_pixels:
  * @name: The brush name.
- * @width: The brush width.
- * @height: The brush height.
- * @mask_bpp: The brush mask bpp.
- * @num_mask_bytes: Length of brush mask data.
- * @mask_bytes: (element-type guint8) (transfer full) The brush mask data.
- * @color_bpp: The brush color bpp.
- * @num_color_bytes: Length of brush color data.
- * @color_bytes: (element-type guint8) (transfer full) The brush color data.
+ * @width: (out) The brush width.
+ * @height: (out) The brush height.
+ * @mask_bpp: (out) The brush mask bpp.
+ * @num_mask_bytes: (out) Length of brush mask data.
+ * @mask_bytes: (out) (element-type guint8) (transfer full) The brush mask data.
+ * @color_bpp: (out) The brush color bpp.
+ * @num_color_bytes: (out) Length of brush color data.
+ * @color_bytes: (out) (element-type guint8) (transfer full) The brush color data.
  *
  * Retrieves information about the specified brush.
  *
@@ -381,7 +381,7 @@ gimp_brush_get_pixels (const gchar  *name,
 /**
  * gimp_brush_get_spacing:
  * @name: The brush name.
- * @spacing: The brush spacing.
+ * @spacing: (out) The brush spacing.
  *
  * Gets the brush spacing.
  *
diff --git a/libgimp/gimpbrushes_pdb.c b/libgimp/gimpbrushes_pdb.c
index 2a5ac081aa..69f3ef2e3f 100644
--- a/libgimp/gimpbrushes_pdb.c
+++ b/libgimp/gimpbrushes_pdb.c
@@ -67,7 +67,7 @@ gimp_brushes_refresh (void)
 /**
  * gimp_brushes_get_list:
  * @filter: An optional regular expression used to filter the list.
- * @num_brushes: The number of brushes in the brush list.
+ * @num_brushes: (out) The number of brushes in the brush list.
  *
  * Retrieve a complete listing of the available brushes.
  *
diff --git a/libgimp/gimpbuffer_pdb.c b/libgimp/gimpbuffer_pdb.c
index 5cb3971a7e..c94656ce32 100644
--- a/libgimp/gimpbuffer_pdb.c
+++ b/libgimp/gimpbuffer_pdb.c
@@ -37,7 +37,7 @@
 /**
  * gimp_buffers_get_list:
  * @filter: An optional regular expression used to filter the list.
- * @num_buffers: The number of buffers.
+ * @num_buffers: (out) The number of buffers.
  *
  * Retrieve a complete listing of the available buffers.
  *
diff --git a/libgimp/gimpchannel_pdb.c b/libgimp/gimpchannel_pdb.c
index 804a0b1aab..27a635f849 100644
--- a/libgimp/gimpchannel_pdb.c
+++ b/libgimp/gimpchannel_pdb.c
@@ -369,7 +369,7 @@ gimp_channel_set_opacity (gint32  channel_ID,
 /**
  * gimp_channel_get_color:
  * @channel_ID: The channel.
- * @color: The channel compositing color.
+ * @color: (out) The channel compositing color.
  *
  * Get the compositing color of the specified channel.
  *
diff --git a/libgimp/gimpcontext_pdb.c b/libgimp/gimpcontext_pdb.c
index 5c59fdeded..7344c9b866 100644
--- a/libgimp/gimpcontext_pdb.c
+++ b/libgimp/gimpcontext_pdb.c
@@ -138,8 +138,8 @@ gimp_context_set_defaults (void)
 
 /**
  * gimp_context_list_paint_methods:
- * @num_paint_methods: The number of the available paint methods.
- * @paint_methods: (element-type gchar*) (transfer full) The names of the available paint methods.
+ * @num_paint_methods: (out) The number of the available paint methods.
+ * @paint_methods: (out) (element-type gchar*) (transfer full) The names of the available paint methods.
  *
  * Lists the available paint methods.
  *
@@ -322,7 +322,7 @@ gimp_context_set_stroke_method (GimpStrokeMethod stroke_method)
 
 /**
  * gimp_context_get_foreground:
- * @foreground: The foreground color.
+ * @foreground: (out) The foreground color.
  *
  * Get the current GIMP foreground color.
  *
@@ -395,7 +395,7 @@ gimp_context_set_foreground (const GimpRGB *foreground)
 
 /**
  * gimp_context_get_background:
- * @background: The background color.
+ * @background: (out) The background color.
  *
  * Get the current GIMP background color.
  *
@@ -1099,8 +1099,8 @@ gimp_context_set_line_dash_offset (gdouble dash_offset)
 
 /**
  * gimp_context_get_line_dash_pattern:
- * @num_dashes: The number of dashes in the dash_pattern array.
- * @dashes: (elemen-type gdouble) (transfer full) The line dash pattern setting.
+ * @num_dashes: (out) The number of dashes in the dash_pattern array.
+ * @dashes: (out) (elemen-type gdouble) (transfer full) The line dash pattern setting.
  *
  * Get the line dash pattern setting.
  *
@@ -2672,8 +2672,8 @@ gimp_context_set_feather (gboolean feather)
 
 /**
  * gimp_context_get_feather_radius:
- * @feather_radius_x: The horizontal feather radius.
- * @feather_radius_y: The vertical feather radius.
+ * @feather_radius_x: (out) The horizontal feather radius.
+ * @feather_radius_y: (out) The vertical feather radius.
  *
  * Get the feather radius setting.
  *
diff --git a/libgimp/gimpdrawable_pdb.c b/libgimp/gimpdrawable_pdb.c
index f7d782a08b..aa1bde4f11 100644
--- a/libgimp/gimpdrawable_pdb.c
+++ b/libgimp/gimpdrawable_pdb.c
@@ -417,8 +417,8 @@ gimp_drawable_height (gint32 drawable_ID)
 /**
  * gimp_drawable_offsets:
  * @drawable_ID: The drawable.
- * @offset_x: x offset of drawable.
- * @offset_y: y offset of drawable.
+ * @offset_x: (out) x offset of drawable.
+ * @offset_y: (out) y offset of drawable.
  *
  * Returns the offsets for the drawable.
  *
@@ -464,10 +464,10 @@ gimp_drawable_offsets (gint32  drawable_ID,
 /**
  * gimp_drawable_mask_bounds:
  * @drawable_ID: The drawable.
- * @x1: x coordinate of the upper left corner of selection bounds.
- * @y1: y coordinate of the upper left corner of selection bounds.
- * @x2: x coordinate of the lower right corner of selection bounds.
- * @y2: y coordinate of the lower right corner of selection bounds.
+ * @x1: (out) x coordinate of the upper left corner of selection bounds.
+ * @y1: (out) y coordinate of the upper left corner of selection bounds.
+ * @x2: (out) x coordinate of the lower right corner of selection bounds.
+ * @y2: (out) y coordinate of the lower right corner of selection bounds.
  *
  * Find the bounding box of the current selection in relation to the
  * specified drawable.
@@ -523,10 +523,10 @@ gimp_drawable_mask_bounds (gint32  drawable_ID,
 /**
  * gimp_drawable_mask_intersect:
  * @drawable_ID: The drawable.
- * @x: x coordinate of the upper left corner of the intersection.
- * @y: y coordinate of the upper left corner of the intersection.
- * @width: width of the intersection.
- * @height: height of the intersection.
+ * @x: (out) x coordinate of the upper left corner of the intersection.
+ * @y: (out) y coordinate of the upper left corner of the intersection.
+ * @width: (out) width of the intersection.
+ * @height: (out) height of the intersection.
  *
  * Find the bounding box of the current selection in relation to the
  * specified drawable.
@@ -706,7 +706,7 @@ gimp_drawable_update (gint32 drawable_ID,
  * @drawable_ID: The drawable.
  * @x_coord: The x coordinate.
  * @y_coord: The y coordinate.
- * @num_channels: The number of channels for the pixel.
+ * @num_channels: (out) The number of channels for the pixel.
  *
  * Gets the value of the pixel at the specified coordinates.
  *
@@ -908,11 +908,11 @@ gimp_drawable_offset (gint32         drawable_ID,
  * @drawable_ID: The drawable.
  * @width: The requested thumbnail width.
  * @height: The requested thumbnail height.
- * @actual_width: The previews width.
- * @actual_height: The previews height.
- * @bpp: The previews bpp.
- * @thumbnail_data_count: The number of bytes in thumbnail data.
- * @thumbnail_data: (element-type guint8) (transfer full) The thumbnail data.
+ * @actual_width: (out) The previews width.
+ * @actual_height: (out) The previews height.
+ * @bpp: (out) The previews bpp.
+ * @thumbnail_data_count: (out) The number of bytes in thumbnail data.
+ * @thumbnail_data: (out) (element-type guint8) (transfer full) The thumbnail data.
  *
  * Get a thumbnail of a drawable.
  *
@@ -980,11 +980,11 @@ _gimp_drawable_thumbnail (gint32   drawable_ID,
  * @src_height: The height of the area.
  * @dest_width: The thumbnail width.
  * @dest_height: The thumbnail height.
- * @width: The previews width.
- * @height: The previews height.
- * @bpp: The previews bpp.
- * @thumbnail_data_count: The number of bytes in thumbnail data.
- * @thumbnail_data: (element-type guint8) (transfer full) The thumbnail data.
+ * @width: (out) The previews width.
+ * @height: (out) The previews height.
+ * @bpp: (out) The previews bpp.
+ * @thumbnail_data_count: (out) The number of bytes in thumbnail data.
+ * @thumbnail_data: (out) (element-type guint8) (transfer full) The thumbnail data.
  *
  * Get a thumbnail of a sub-area of a drawable drawable.
  *
diff --git a/libgimp/gimpdrawablecolor_pdb.c b/libgimp/gimpdrawablecolor_pdb.c
index d7b3dfd840..ffbb9a8391 100644
--- a/libgimp/gimpdrawablecolor_pdb.c
+++ b/libgimp/gimpdrawablecolor_pdb.c
@@ -382,12 +382,12 @@ gimp_drawable_equalize (gint32   drawable_ID,
  * @channel: The channel to query.
  * @start_range: Start of the intensity measurement range.
  * @end_range: End of the intensity measurement range.
- * @mean: Mean intensity value.
- * @std_dev: Standard deviation of intensity values.
- * @median: Median intensity value.
- * @pixels: Alpha-weighted pixel count for entire image.
- * @count: Alpha-weighted pixel count for range.
- * @percentile: Percentile that range falls under.
+ * @mean: (out) Mean intensity value.
+ * @std_dev: (out) Standard deviation of intensity values.
+ * @median: (out) Median intensity value.
+ * @pixels: (out) Alpha-weighted pixel count for entire image.
+ * @count: (out) Alpha-weighted pixel count for range.
+ * @percentile: (out) Percentile that range falls under.
  *
  * Returns information on the intensity histogram for the specified
  * drawable.
diff --git a/libgimp/gimpdynamics_pdb.c b/libgimp/gimpdynamics_pdb.c
index 58b915c2b0..aa60ea16bd 100644
--- a/libgimp/gimpdynamics_pdb.c
+++ b/libgimp/gimpdynamics_pdb.c
@@ -70,7 +70,7 @@ gimp_dynamics_refresh (void)
 /**
  * gimp_dynamics_get_list:
  * @filter: An optional regular expression used to filter the list.
- * @num_dynamics: The number of available paint dynamics.
+ * @num_dynamics: (out) The number of available paint dynamics.
  *
  * Retrieve the list of loaded paint dynamics.
  *
diff --git a/libgimp/gimpfileops_pdb.c b/libgimp/gimpfileops_pdb.c
index 41864983dd..d27c70620c 100644
--- a/libgimp/gimpfileops_pdb.c
+++ b/libgimp/gimpfileops_pdb.c
@@ -132,7 +132,7 @@ gimp_file_load_layer (GimpRunMode  run_mode,
  * @run_mode: The run mode.
  * @image_ID: Destination image.
  * @filename: The name of the file to load.
- * @num_layers: The number of loaded layers.
+ * @num_layers: (out) The number of loaded layers.
  *
  * Loads an image file as layers for an existing image.
  *
diff --git a/libgimp/gimpfonts_pdb.c b/libgimp/gimpfonts_pdb.c
index 9c15ea8e19..24b6739849 100644
--- a/libgimp/gimpfonts_pdb.c
+++ b/libgimp/gimpfonts_pdb.c
@@ -68,7 +68,7 @@ gimp_fonts_refresh (void)
 /**
  * gimp_fonts_get_list:
  * @filter: An optional regular expression used to filter the list.
- * @num_fonts: The number of available fonts.
+ * @num_fonts: (out) The number of available fonts.
  *
  * Retrieve the list of loaded fonts.
  *
diff --git a/libgimp/gimpgimprc_pdb.c b/libgimp/gimpgimprc_pdb.c
index 02ff43d976..2b7e5366cd 100644
--- a/libgimp/gimpgimprc_pdb.c
+++ b/libgimp/gimpgimprc_pdb.c
@@ -180,8 +180,8 @@ gimp_get_default_unit (void)
 
 /**
  * gimp_get_monitor_resolution:
- * @xres: X resolution.
- * @yres: Y resolution.
+ * @xres: (out) X resolution.
+ * @yres: (out) Y resolution.
  *
  * Get the monitor resolution as specified in the Preferences.
  *
diff --git a/libgimp/gimpgradient_pdb.c b/libgimp/gimpgradient_pdb.c
index caf37c40f2..5c7c9bba16 100644
--- a/libgimp/gimpgradient_pdb.c
+++ b/libgimp/gimpgradient_pdb.c
@@ -253,8 +253,8 @@ gimp_gradient_get_number_of_segments (const gchar *name)
  * @name: The gradient name.
  * @num_samples: The number of samples to take.
  * @reverse: Use the reverse gradient.
- * @num_color_samples: Length of the color_samples array (4 * num_samples).
- * @color_samples: (elemen-type gdouble) (transfer full) Color samples: { R1, G1, B1, A1, ..., Rn, Gn, Bn, An }.
+ * @num_color_samples: (out) Length of the color_samples array (4 * num_samples).
+ * @color_samples: (out) (elemen-type gdouble) (transfer full) Color samples: { R1, G1, B1, A1, ..., Rn, Gn, Bn, An }.
  *
  * Sample the specified in uniform parts.
  *
@@ -315,8 +315,8 @@ gimp_gradient_get_uniform_samples (const gchar  *name,
  * @num_samples: The number of samples to take.
  * @positions: The list of positions to sample along the gradient.
  * @reverse: Use the reverse gradient.
- * @num_color_samples: Length of the color_samples array (4 * num_samples).
- * @color_samples: (elemen-type gdouble) (transfer full) Color samples: { R1, G1, B1, A1, ..., Rn, Gn, Bn, An }.
+ * @num_color_samples: (out) Length of the color_samples array (4 * num_samples).
+ * @color_samples: (out) (elemen-type gdouble) (transfer full) Color samples: { R1, G1, B1, A1, ..., Rn, Gn, Bn, An }.
  *
  * Sample the specified gradient in custom positions.
  *
@@ -377,8 +377,8 @@ gimp_gradient_get_custom_samples (const gchar    *name,
  * gimp_gradient_segment_get_left_color:
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
- * @color: The return color.
- * @opacity: The opacity of the endpoint.
+ * @color: (out) The return color.
+ * @opacity: (out) The opacity of the endpoint.
  *
  * Retrieves the left endpoint color of the specified segment
  *
@@ -475,8 +475,8 @@ gimp_gradient_segment_set_left_color (const gchar   *name,
  * gimp_gradient_segment_get_right_color:
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
- * @color: The return color.
- * @opacity: The opacity of the endpoint.
+ * @color: (out) The return color.
+ * @opacity: (out) The opacity of the endpoint.
  *
  * Retrieves the right endpoint color of the specified segment
  *
@@ -573,7 +573,7 @@ gimp_gradient_segment_set_right_color (const gchar   *name,
  * gimp_gradient_segment_get_left_pos:
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
- * @pos: The return position.
+ * @pos: (out) The return position.
  *
  * Retrieves the left endpoint position of the specified segment
  *
@@ -620,7 +620,7 @@ gimp_gradient_segment_get_left_pos (const gchar *name,
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
  * @pos: The position to set the guidepoint to.
- * @final_pos: The return position.
+ * @final_pos: (out) The return position.
  *
  * Sets the left endpoint position of the specified segment
  *
@@ -672,7 +672,7 @@ gimp_gradient_segment_set_left_pos (const gchar *name,
  * gimp_gradient_segment_get_middle_pos:
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
- * @pos: The return position.
+ * @pos: (out) The return position.
  *
  * Retrieves the middle point position of the specified segment
  *
@@ -719,7 +719,7 @@ gimp_gradient_segment_get_middle_pos (const gchar *name,
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
  * @pos: The position to set the guidepoint to.
- * @final_pos: The return position.
+ * @final_pos: (out) The return position.
  *
  * Sets the middle point position of the specified segment
  *
@@ -770,7 +770,7 @@ gimp_gradient_segment_set_middle_pos (const gchar *name,
  * gimp_gradient_segment_get_right_pos:
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
- * @pos: The return position.
+ * @pos: (out) The return position.
  *
  * Retrieves the right endpoint position of the specified segment
  *
@@ -817,7 +817,7 @@ gimp_gradient_segment_get_right_pos (const gchar *name,
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
  * @pos: The position to set the guidepoint to.
- * @final_pos: The return position.
+ * @final_pos: (out) The return position.
  *
  * Sets the right endpoint position of the specified segment
  *
@@ -869,7 +869,7 @@ gimp_gradient_segment_set_right_pos (const gchar *name,
  * gimp_gradient_segment_get_blending_function:
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
- * @blend_func: The blending function of the segment.
+ * @blend_func: (out) The blending function of the segment.
  *
  * Retrieves the gradient segment's blending function
  *
@@ -915,7 +915,7 @@ gimp_gradient_segment_get_blending_function (const gchar             *name,
  * gimp_gradient_segment_get_coloring_type:
  * @name: The gradient name.
  * @segment: The index of the segment within the gradient.
- * @coloring_type: The coloring type of the segment.
+ * @coloring_type: (out) The coloring type of the segment.
  *
  * Retrieves the gradient segment's coloring type
  *
diff --git a/libgimp/gimpgradients_pdb.c b/libgimp/gimpgradients_pdb.c
index 55bdd0049c..13b18664ba 100644
--- a/libgimp/gimpgradients_pdb.c
+++ b/libgimp/gimpgradients_pdb.c
@@ -67,7 +67,7 @@ gimp_gradients_refresh (void)
 /**
  * gimp_gradients_get_list:
  * @filter: An optional regular expression used to filter the list.
- * @num_gradients: The number of loaded gradients.
+ * @num_gradients: (out) The number of loaded gradients.
  *
  * Retrieve the list of loaded gradients.
  *
diff --git a/libgimp/gimpimage_pdb.c b/libgimp/gimpimage_pdb.c
index 6fc9cf92ab..b1142ced93 100644
--- a/libgimp/gimpimage_pdb.c
+++ b/libgimp/gimpimage_pdb.c
@@ -73,7 +73,7 @@ gimp_image_is_valid (gint32 image_ID)
 
 /**
  * gimp_image_list:
- * @num_images: The number of images currently open.
+ * @num_images: (out) The number of images currently open.
  *
  * Returns the list of images currently open.
  *
@@ -455,7 +455,7 @@ gimp_image_height (gint32 image_ID)
 /**
  * gimp_image_get_layers:
  * @image_ID: The image.
- * @num_layers: The number of layers contained in the image.
+ * @num_layers: (out) The number of layers contained in the image.
  *
  * Returns the list of layers contained in the specified image.
  *
@@ -498,7 +498,7 @@ gimp_image_get_layers (gint32  image_ID,
 /**
  * gimp_image_get_channels:
  * @image_ID: The image.
- * @num_channels: The number of channels contained in the image.
+ * @num_channels: (out) The number of channels contained in the image.
  *
  * Returns the list of channels contained in the specified image.
  *
@@ -544,7 +544,7 @@ gimp_image_get_channels (gint32  image_ID,
 /**
  * gimp_image_get_vectors:
  * @image_ID: The image.
- * @num_vectors: The number of vectors contained in the image.
+ * @num_vectors: (out) The number of vectors contained in the image.
  *
  * Returns the list of vectors contained in the specified image.
  *
@@ -737,7 +737,7 @@ gimp_image_floating_sel_attached_to (gint32 image_ID)
  * @sample_merged: Use the composite image, not the drawable.
  * @sample_average: Average the color of all the pixels in a specified radius.
  * @average_radius: The radius of pixels to average.
- * @color: The return color.
+ * @color: (out) The return color.
  *
  * Determine the color at the given drawable coordinates
  *
@@ -1721,7 +1721,7 @@ gimp_image_merge_down (gint32        image_ID,
 /**
  * _gimp_image_get_colormap:
  * @image_ID: The image.
- * @num_bytes: Number of bytes in the colormap array.
+ * @num_bytes: (out) Number of bytes in the colormap array.
  *
  * Returns the image's colormap
  *
@@ -1954,11 +1954,11 @@ gimp_image_is_dirty (gint32 image_ID)
  * @image_ID: The image.
  * @width: The requested thumbnail width.
  * @height: The requested thumbnail height.
- * @actual_width: The previews width.
- * @actual_height: The previews height.
- * @bpp: The previews bpp.
- * @thumbnail_data_count: The number of bytes in thumbnail data.
- * @thumbnail_data: (element-type guint8) (transfer full) The thumbnail data.
+ * @actual_width: (out) The previews width.
+ * @actual_height: (out) The previews height.
+ * @bpp: (out) The previews bpp.
+ * @thumbnail_data_count: (out) The number of bytes in thumbnail data.
+ * @thumbnail_data: (out) (element-type guint8) (transfer full) The thumbnail data.
  *
  * Get a thumbnail of an image.
  *
@@ -2708,8 +2708,8 @@ gimp_image_get_name (gint32 image_ID)
 /**
  * gimp_image_get_resolution:
  * @image_ID: The image.
- * @xresolution: The resolution in the x-axis, in dots per inch.
- * @yresolution: The resolution in the y-axis, in dots per inch.
+ * @xresolution: (out) The resolution in the x-axis, in dots per inch.
+ * @yresolution: (out) The resolution in the y-axis, in dots per inch.
  *
  * Returns the specified image's resolution.
  *
@@ -3308,7 +3308,7 @@ gimp_image_get_parasite (gint32       image_ID,
 /**
  * gimp_image_get_parasite_list:
  * @image_ID: The image.
- * @num_parasites: The number of attached parasites.
+ * @num_parasites: (out) The number of attached parasites.
  *
  * List all parasites.
  *
diff --git a/libgimp/gimpimagecolorprofile_pdb.c b/libgimp/gimpimagecolorprofile_pdb.c
index 3f5e168c07..a7bdd7e0e6 100644
--- a/libgimp/gimpimagecolorprofile_pdb.c
+++ b/libgimp/gimpimagecolorprofile_pdb.c
@@ -37,7 +37,7 @@
 /**
  * _gimp_image_get_color_profile:
  * @image_ID: The image.
- * @num_bytes: Number of bytes in the color_profile array.
+ * @num_bytes: (out) Number of bytes in the color_profile array.
  *
  * Returns the image's color profile
  *
@@ -82,7 +82,7 @@ _gimp_image_get_color_profile (gint32  image_ID,
 /**
  * _gimp_image_get_effective_color_profile:
  * @image_ID: The image.
- * @num_bytes: Number of bytes in the color_profile array.
+ * @num_bytes: (out) Number of bytes in the color_profile array.
  *
  * Returns the color profile that is used for the image
  *
diff --git a/libgimp/gimpimagegrid_pdb.c b/libgimp/gimpimagegrid_pdb.c
index 92587f524c..6990beb5c1 100644
--- a/libgimp/gimpimagegrid_pdb.c
+++ b/libgimp/gimpimagegrid_pdb.c
@@ -37,8 +37,8 @@
 /**
  * gimp_image_grid_get_spacing:
  * @image_ID: The image.
- * @xspacing: The image's grid horizontal spacing.
- * @yspacing: The image's grid vertical spacing.
+ * @xspacing: (out) The image's grid horizontal spacing.
+ * @yspacing: (out) The image's grid vertical spacing.
  *
  * Gets the spacing of an image's grid.
  *
@@ -128,8 +128,8 @@ gimp_image_grid_set_spacing (gint32  image_ID,
 /**
  * gimp_image_grid_get_offset:
  * @image_ID: The image.
- * @xoffset: The image's grid horizontal offset.
- * @yoffset: The image's grid vertical offset.
+ * @xoffset: (out) The image's grid horizontal offset.
+ * @yoffset: (out) The image's grid vertical offset.
  *
  * Gets the offset of an image's grid.
  *
@@ -219,7 +219,7 @@ gimp_image_grid_set_offset (gint32  image_ID,
 /**
  * gimp_image_grid_get_foreground_color:
  * @image_ID: The image.
- * @fgcolor: The image's grid foreground color.
+ * @fgcolor: (out) The image's grid foreground color.
  *
  * Sets the foreground color of an image's grid.
  *
@@ -296,7 +296,7 @@ gimp_image_grid_set_foreground_color (gint32         image_ID,
 /**
  * gimp_image_grid_get_background_color:
  * @image_ID: The image.
- * @bgcolor: The image's grid background color.
+ * @bgcolor: (out) The image's grid background color.
  *
  * Sets the background color of an image's grid.
  *
diff --git a/libgimp/gimpimagesamplepoints_pdb.c b/libgimp/gimpimagesamplepoints_pdb.c
index ae587159b8..ec54dc9880 100644
--- a/libgimp/gimpimagesamplepoints_pdb.c
+++ b/libgimp/gimpimagesamplepoints_pdb.c
@@ -166,7 +166,7 @@ gimp_image_find_next_sample_point (gint32 image_ID,
  * gimp_image_get_sample_point_position:
  * @image_ID: The image.
  * @sample_point_ID: The guide.
- * @position_y: The sample points's position relative to top of image.
+ * @position_y: (out) The sample points's position relative to top of image.
  *
  * Get position of a sample point on an image.
  *
diff --git a/libgimp/gimpitem_pdb.c b/libgimp/gimpitem_pdb.c
index 4873141303..2b67299d3d 100644
--- a/libgimp/gimpitem_pdb.c
+++ b/libgimp/gimpitem_pdb.c
@@ -462,7 +462,7 @@ gimp_item_get_parent (gint32 item_ID)
 /**
  * gimp_item_get_children:
  * @item_ID: The item.
- * @num_children: The item's number of children.
+ * @num_children: (out) The item's number of children.
  *
  * Returns the item's list of children.
  *
@@ -1211,7 +1211,7 @@ gimp_item_get_parasite (gint32       item_ID,
 /**
  * gimp_item_get_parasite_list:
  * @item_ID: The item.
- * @num_parasites: The number of attached parasites.
+ * @num_parasites: (out) The number of attached parasites.
  *
  * List all parasites.
  *
diff --git a/libgimp/gimppalette_pdb.c b/libgimp/gimppalette_pdb.c
index d2f33e38d6..eace9c70be 100644
--- a/libgimp/gimppalette_pdb.c
+++ b/libgimp/gimppalette_pdb.c
@@ -215,7 +215,7 @@ gimp_palette_is_editable (const gchar *name)
 /**
  * gimp_palette_get_info:
  * @name: The palette name.
- * @num_colors: (out): The number of colors in the palette.
+ * @num_colors: (out) (out): The number of colors in the palette.
  *
  * Retrieve information about the specified palette.
  *
@@ -257,7 +257,7 @@ gimp_palette_get_info (const gchar *name,
 /**
  * gimp_palette_get_colors:
  * @name: The palette name.
- * @num_colors: Length of the colors array.
+ * @num_colors: (out) Length of the colors array.
  *
  * Gets all colors from the specified palette.
  *
@@ -378,7 +378,7 @@ gimp_palette_set_columns (const gchar *name,
  * @name: The palette name.
  * @entry_name: The name of the entry.
  * @color: The new entry's color color.
- * @entry_num: The index of the added entry.
+ * @entry_num: (out) The index of the added entry.
  *
  * Adds a palette entry to the specified palette.
  *
@@ -466,7 +466,7 @@ gimp_palette_delete_entry (const gchar *name,
  * gimp_palette_entry_get_color:
  * @name: The palette name.
  * @entry_num: The entry to retrieve.
- * @color: (out): The color requested.
+ * @color: (out) (out): The color requested.
  *
  * Gets the specified palette entry from the specified palette.
  *
@@ -555,7 +555,7 @@ gimp_palette_entry_set_color (const gchar   *name,
  * gimp_palette_entry_get_name:
  * @name: The palette name.
  * @entry_num: The entry to retrieve.
- * @entry_name: (transfer full) The name requested.
+ * @entry_name: (out) (transfer full) The name requested.
  *
  * Gets the specified palette entry from the specified palette.
  *
diff --git a/libgimp/gimppalettes_pdb.c b/libgimp/gimppalettes_pdb.c
index 08d3626c5d..95fbb83fb6 100644
--- a/libgimp/gimppalettes_pdb.c
+++ b/libgimp/gimppalettes_pdb.c
@@ -67,7 +67,7 @@ gimp_palettes_refresh (void)
 /**
  * gimp_palettes_get_list:
  * @filter: An optional regular expression used to filter the list.
- * @num_palettes: The number of palettes in the list.
+ * @num_palettes: (out) The number of palettes in the list.
  *
  * Retrieves a list of all of the available palettes
  *
diff --git a/libgimp/gimppattern_pdb.c b/libgimp/gimppattern_pdb.c
index 1d79e8a762..97ddc60660 100644
--- a/libgimp/gimppattern_pdb.c
+++ b/libgimp/gimppattern_pdb.c
@@ -37,9 +37,9 @@
 /**
  * gimp_pattern_get_info:
  * @name: The pattern name.
- * @width: The pattern width.
- * @height: The pattern height.
- * @bpp: The pattern bpp.
+ * @width: (out) The pattern width.
+ * @height: (out) The pattern height.
+ * @bpp: (out) The pattern bpp.
  *
  * Retrieve information about the specified pattern.
  *
@@ -89,11 +89,11 @@ gimp_pattern_get_info (const gchar *name,
 /**
  * gimp_pattern_get_pixels:
  * @name: The pattern name.
- * @width: The pattern width.
- * @height: The pattern height.
- * @bpp: The pattern bpp.
- * @num_color_bytes: Number of pattern bytes.
- * @color_bytes: (element-type guint8) (transfer full) The pattern data.
+ * @width: (out) The pattern width.
+ * @height: (out) The pattern height.
+ * @bpp: (out) The pattern bpp.
+ * @num_color_bytes: (out) Number of pattern bytes.
+ * @color_bytes: (out) (element-type guint8) (transfer full) The pattern data.
  *
  * Retrieve information about the specified pattern (including pixels).
  *
diff --git a/libgimp/gimppatterns_pdb.c b/libgimp/gimppatterns_pdb.c
index 53a3128f48..c500667240 100644
--- a/libgimp/gimppatterns_pdb.c
+++ b/libgimp/gimppatterns_pdb.c
@@ -67,7 +67,7 @@ gimp_patterns_refresh (void)
 /**
  * gimp_patterns_get_list:
  * @filter: An optional regular expression used to filter the list.
- * @num_patterns: The number of patterns in the pattern list.
+ * @num_patterns: (out) The number of patterns in the pattern list.
  *
  * Retrieve a complete listing of the available patterns.
  *
diff --git a/libgimp/gimpproceduraldb_pdb.c b/libgimp/gimpproceduraldb_pdb.c
index b8ade0e814..621177ea48 100644
--- a/libgimp/gimpproceduraldb_pdb.c
+++ b/libgimp/gimpproceduraldb_pdb.c
@@ -110,8 +110,8 @@ gimp_procedural_db_dump (const gchar *filename)
  * @copyright: The regex for procedure copyright.
  * @date: The regex for procedure date.
  * @proc_type: The regex for procedure type: { 'Internal GIMP procedure', 'GIMP Plug-in', 'GIMP Extension', 'Temporary Procedure' }.
- * @num_matches: The number of matching procedures.
- * @procedure_names: (element-type gchar*) (transfer full) The list of procedure names.
+ * @num_matches: (out) The number of matching procedures.
+ * @procedure_names: (out) (element-type gchar*) (transfer full) The list of procedure names.
  *
  * Queries the procedural database for its contents using regular
  * expression matching.
@@ -221,14 +221,14 @@ gimp_procedural_db_proc_exists (const gchar *procedure_name)
 /**
  * _gimp_procedural_db_proc_info:
  * @procedure_name: The procedure name.
- * @blurb: (transfer full) A short blurb.
- * @help: (transfer full) Detailed procedure help.
- * @author: (transfer full) Author(s) of the procedure.
- * @copyright: (transfer full) The copyright.
- * @date: (transfer full) Copyright date.
- * @proc_type: The procedure type.
- * @num_args: The number of input arguments.
- * @num_values: The number of return values.
+ * @blurb: (out) (transfer full) A short blurb.
+ * @help: (out) (transfer full) Detailed procedure help.
+ * @author: (out) (transfer full) Author(s) of the procedure.
+ * @copyright: (out) (transfer full) The copyright.
+ * @date: (out) (transfer full) Copyright date.
+ * @proc_type: (out) The procedure type.
+ * @num_args: (out) The number of input arguments.
+ * @num_values: (out) The number of return values.
  *
  * Queries the procedural database for information on the specified
  * procedure.
@@ -297,9 +297,9 @@ _gimp_procedural_db_proc_info (const gchar      *procedure_name,
  * gimp_procedural_db_proc_arg:
  * @procedure_name: The procedure name.
  * @arg_num: The argument number.
- * @arg_type: The type of argument.
- * @arg_name: (transfer full) The name of the argument.
- * @arg_desc: (transfer full) A description of the argument.
+ * @arg_type: (out) The type of argument.
+ * @arg_name: (out) (transfer full) The name of the argument.
+ * @arg_desc: (out) (transfer full) A description of the argument.
  *
  * Queries the procedural database for information on the specified
  * procedure's argument.
@@ -352,9 +352,9 @@ gimp_procedural_db_proc_arg (const gchar     *procedure_name,
  * gimp_procedural_db_proc_val:
  * @procedure_name: The procedure name.
  * @val_num: The return value number.
- * @val_type: The type of return value.
- * @val_name: (transfer full) The name of the return value.
- * @val_desc: (transfer full) A description of the return value.
+ * @val_type: (out) The type of return value.
+ * @val_name: (out) (transfer full) The name of the return value.
+ * @val_desc: (out) (transfer full) A description of the return value.
  *
  * Queries the procedural database for information on the specified
  * procedure's return value.
@@ -407,8 +407,8 @@ gimp_procedural_db_proc_val (const gchar     *procedure_name,
 /**
  * _gimp_procedural_db_get_data:
  * @identifier: The identifier associated with data.
- * @bytes: The number of bytes in the data.
- * @data: (element-type guint8) (transfer full) A byte array containing data.
+ * @bytes: (out) The number of bytes in the data.
+ * @data: (out) (element-type guint8) (transfer full) A byte array containing data.
  *
  * Returns data associated with the specified identifier.
  *
diff --git a/libgimp/gimpselection_pdb.c b/libgimp/gimpselection_pdb.c
index b44862a6d2..5bfedfb789 100644
--- a/libgimp/gimpselection_pdb.c
+++ b/libgimp/gimpselection_pdb.c
@@ -37,11 +37,11 @@
 /**
  * gimp_selection_bounds:
  * @image_ID: The image.
- * @non_empty: TRUE if there is a selection.
- * @x1: x coordinate of upper left corner of selection bounds.
- * @y1: y coordinate of upper left corner of selection bounds.
- * @x2: x coordinate of lower right corner of selection bounds.
- * @y2: y coordinate of lower right corner of selection bounds.
+ * @non_empty: (out) TRUE if there is a selection.
+ * @x1: (out) x coordinate of upper left corner of selection bounds.
+ * @y1: (out) y coordinate of upper left corner of selection bounds.
+ * @x2: (out) x coordinate of lower right corner of selection bounds.
+ * @y2: (out) y coordinate of lower right corner of selection bounds.
  *
  * Find the bounding box of the current selection.
  *
diff --git a/libgimp/gimptextlayer_pdb.c b/libgimp/gimptextlayer_pdb.c
index 072d8ca11c..3f790ed5fd 100644
--- a/libgimp/gimptextlayer_pdb.c
+++ b/libgimp/gimptextlayer_pdb.c
@@ -280,7 +280,7 @@ gimp_text_layer_set_font (gint32       layer_ID,
 /**
  * gimp_text_layer_get_font_size:
  * @layer_ID: The text layer.
- * @unit: The unit used for the font size.
+ * @unit: (out) The unit used for the font size.
  *
  * Get the font size from a text layer.
  *
@@ -817,7 +817,7 @@ gimp_text_layer_set_justification (gint32                layer_ID,
 /**
  * gimp_text_layer_get_color:
  * @layer_ID: The text layer.
- * @color: The color of the text.
+ * @color: (out) The color of the text.
  *
  * Get the color of the text in a text layer.
  *
diff --git a/libgimp/gimptexttool_pdb.c b/libgimp/gimptexttool_pdb.c
index a39b5a40cf..4d98675e85 100644
--- a/libgimp/gimptexttool_pdb.c
+++ b/libgimp/gimptexttool_pdb.c
@@ -122,10 +122,10 @@ gimp_text_fontname (gint32        image_ID,
  * @size: The size of text in either pixels or points.
  * @size_type: The units of specified size.
  * @fontname: The name of the font.
- * @width: The width of the specified font.
- * @height: The height of the specified font.
- * @ascent: The ascent of the specified font.
- * @descent: The descent of the specified font.
+ * @width: (out) The width of the specified font.
+ * @height: (out) The height of the specified font.
+ * @ascent: (out) The ascent of the specified font.
+ * @descent: (out) The descent of the specified font.
  *
  * Get extents of the bounding box for the specified text.
  *
diff --git a/libgimp/gimpvectors_pdb.c b/libgimp/gimpvectors_pdb.c
index ef5145a6e9..ea955baca5 100644
--- a/libgimp/gimpvectors_pdb.c
+++ b/libgimp/gimpvectors_pdb.c
@@ -154,7 +154,7 @@ gimp_vectors_copy (gint32 vectors_ID)
 /**
  * gimp_vectors_get_strokes:
  * @vectors_ID: The vectors object.
- * @num_strokes: The number of strokes returned.
+ * @num_strokes: (out) The number of strokes returned.
  *
  * List the strokes associated with the passed path.
  *
@@ -244,10 +244,10 @@ gimp_vectors_stroke_get_length (gint32  vectors_ID,
  * @stroke_id: The stroke ID.
  * @dist: The given distance.
  * @precision: The precision used for the approximation.
- * @x_point: The x position of the point.
- * @y_point: The y position of the point.
- * @slope: The slope (dy / dx) at the specified point.
- * @valid: Indicator for the validity of the returned data.
+ * @x_point: (out) The x position of the point.
+ * @y_point: (out) The y position of the point.
+ * @slope: (out) The slope (dy / dx) at the specified point.
+ * @valid: (out) Indicator for the validity of the returned data.
  *
  * Get point at a specified distance along the stroke.
  *
@@ -634,9 +634,9 @@ gimp_vectors_stroke_flip_free (gint32  vectors_ID,
  * gimp_vectors_stroke_get_points:
  * @vectors_ID: The vectors object.
  * @stroke_id: The stroke ID.
- * @num_points: The number of floats returned.
- * @controlpoints: (elemen-type gdouble) (transfer full) List of the control points for the stroke (x0, y0, x1, y1, ...).
- * @closed: Whether the stroke is closed or not.
+ * @num_points: (out) The number of floats returned.
+ * @controlpoints: (out) (elemen-type gdouble) (transfer full) List of the control points for the stroke (x0, y0, x1, y1, ...).
+ * @closed: (out) Whether the stroke is closed or not.
  *
  * returns the control points of a stroke.
  *
@@ -749,8 +749,8 @@ gimp_vectors_stroke_new_from_points (gint32                 vectors_ID,
  * @vectors_ID: The vectors object.
  * @stroke_id: The stroke ID.
  * @precision: The precision used for the approximation.
- * @num_coords: The number of floats returned.
- * @closed: Whether the stroke is closed or not.
+ * @num_coords: (out) The number of floats returned.
+ * @closed: (out) Whether the stroke is closed or not.
  *
  * returns polygonal approximation of the stroke.
  *
@@ -1066,8 +1066,8 @@ gimp_vectors_bezier_stroke_new_ellipse (gint32  vectors_ID,
  * @filename: The name of the SVG file to import.
  * @merge: Merge paths into a single vectors object.
  * @scale: Scale the SVG to image dimensions.
- * @num_vectors: The number of newly created vectors.
- * @vectors_ids: (element-type gint32) (transfer full) The list of newly created vectors.
+ * @num_vectors: (out) The number of newly created vectors.
+ * @vectors_ids: (out) (element-type gint32) (transfer full) The list of newly created vectors.
  *
  * Import paths from an SVG file.
  *
@@ -1127,8 +1127,8 @@ gimp_vectors_import_from_file (gint32        image_ID,
  * @length: Number of bytes in string or -1 if the string is NULL terminated.
  * @merge: Merge paths into a single vectors object.
  * @scale: Scale the SVG to image dimensions.
- * @num_vectors: The number of newly created vectors.
- * @vectors_ids: (element-type gint32) (transfer full) The list of newly created vectors.
+ * @num_vectors: (out) The number of newly created vectors.
+ * @vectors_ids: (out) (element-type gint32) (transfer full) The list of newly created vectors.
  *
  * Import paths from an SVG string.
  *
diff --git a/pdb/lib.pl b/pdb/lib.pl
index 63743dd482..ec2da7b3e0 100644
--- a/pdb/lib.pl
+++ b/pdb/lib.pl
@@ -328,10 +328,10 @@ CODE
 		    $argdesc .= '_ID' if $arg->{id};
 
 		    if (exists $arg->{return_annotate}) {
-			$argdesc .= ": $arg->{return_annotate} $desc";
+			$argdesc .= ": (out) $arg->{return_annotate} $desc";
 		    }
 		    else {
-			$argdesc .= ": $desc";
+			$argdesc .= ": (out) $desc";
 		    }
 		}