[gimp] libgimpwidgets: add documentation for many functions and fix...

[Jehan <jehanp src gnome org>]

commit 19fbb1d9a8131a6883ffb88b268f82ed8b260250
Author: Jehan <jehan girinstud io>
Date:   Fri Aug 2 11:45:24 2019 +0200

    libgimpwidgets: add documentation for many functions and fix...
    
    ... an annotation.
    s/(transfer-none)/(transfer none)/
    For the "Since:" value, I did some git log archeology. Hopefully I got
    these right.

 libgimpwidgets/gimpcolordisplay.c      | 43 +++++++++++++++++++
 libgimpwidgets/gimpcolordisplaystack.c | 75 ++++++++++++++++++++++++++++++++++
 libgimpwidgets/gimpcolornotebook.c     |  2 +-
 libgimpwidgets/gimpwidgetsutils.c      | 11 +++++
 4 files changed, 130 insertions(+), 1 deletion(-)
---
diff --git a/libgimpwidgets/gimpcolordisplay.c b/libgimpwidgets/gimpcolordisplay.c
index f0bf881a5a..7a0e981e9d 100644
--- a/libgimpwidgets/gimpcolordisplay.c
+++ b/libgimpwidgets/gimpcolordisplay.c
@@ -288,6 +288,16 @@ gimp_color_display_set_color_managed (GimpColorDisplay *display,
     }
 }
 
+/**
+ * gimp_color_display_clone:
+ * @display: a #GimpColorDisplay
+ *
+ * Creates a copy of @display.
+ *
+ * Returns: (transfer full): a duplicate of @display.
+ *
+ * Since: 1.3.10
+ **/
 GimpColorDisplay *
 gimp_color_display_clone (GimpColorDisplay *display)
 {
@@ -326,6 +336,17 @@ gimp_color_display_convert_buffer (GimpColorDisplay *display,
     }
 }
 
+/**
+ * gimp_color_display_load_state:
+ * @display: a #GimpColorDisplay
+ * @state:   a #GimpParasite
+ *
+ * Configures @display from the contents of the parasite @state.
+ * @state must be a properly serialized configuration for a
+ * #GimpColorDisplay, such as saved by gimp_color_display_save_state().
+ *
+ * Since: 1.3.10
+ **/
 void
 gimp_color_display_load_state (GimpColorDisplay *display,
                                GimpParasite     *state)
@@ -339,6 +360,16 @@ gimp_color_display_load_state (GimpColorDisplay *display,
                                   NULL, NULL);
 }
 
+/**
+ * gimp_color_display_save_state:
+ * @display: a #GimpColorDisplay
+ *
+ * Saves the configuration state of @display as a new parasite.
+ *
+ * Returns: (transfer full): a #GimpParasite
+ *
+ * Since: 1.3.10
+ **/
 GimpParasite *
 gimp_color_display_save_state (GimpColorDisplay *display)
 {
@@ -357,6 +388,18 @@ gimp_color_display_save_state (GimpColorDisplay *display)
   return parasite;
 }
 
+/**
+ * gimp_color_display_configure:
+ * @display: a #GimpColorDisplay
+ *
+ * Creates a configuration widget for @display which can be added to a
+ * container widget.
+ *
+ * Returns: (transfer full): a new configuration widget for @display, or
+ *          %NULL if no specific widget exists.
+ *
+ * Since: 1.3.10
+ **/
 GtkWidget *
 gimp_color_display_configure (GimpColorDisplay *display)
 {
diff --git a/libgimpwidgets/gimpcolordisplaystack.c b/libgimpwidgets/gimpcolordisplaystack.c
index d50bdfdbab..061db6ffd6 100644
--- a/libgimpwidgets/gimpcolordisplaystack.c
+++ b/libgimpwidgets/gimpcolordisplaystack.c
@@ -168,12 +168,32 @@ gimp_color_display_stack_dispose (GObject *object)
 
 /*  public functions  */
 
+/**
+ * gimp_color_display_stack_new:
+ *
+ * Creates a new stack of color correction modules.
+ *
+ * Returns: (transfer full): a newly allocated #GimpColorDisplayStack.
+ *
+ * Since: 1.3.23
+ **/
 GimpColorDisplayStack *
 gimp_color_display_stack_new (void)
 {
   return g_object_new (GIMP_TYPE_COLOR_DISPLAY_STACK, NULL);
 }
 
+/**
+ * gimp_color_display_stack_clone:
+ * @stack: a #GimpColorDisplayStack
+ *
+ * Creates a copy of @stack with all its display color modules also
+ * duplicated.
+ *
+ * Returns: (transfer full): a duplicate of @stack.
+ *
+ * Since: 1.3.23
+ **/
 GimpColorDisplayStack *
 gimp_color_display_stack_clone (GimpColorDisplayStack *stack)
 {
@@ -200,6 +220,14 @@ gimp_color_display_stack_clone (GimpColorDisplayStack *stack)
   return clone;
 }
 
+/**
+ * gimp_color_display_stack_changed:
+ * @stack: a #GimpColorDisplayStack
+ *
+ * Emit the "changed" signal of @stack.
+ *
+ * Since: 1.3.23
+ **/
 void
 gimp_color_display_stack_changed (GimpColorDisplayStack *stack)
 {
@@ -208,6 +236,17 @@ gimp_color_display_stack_changed (GimpColorDisplayStack *stack)
   g_signal_emit (stack, stack_signals[CHANGED], 0);
 }
 
+/**
+ * gimp_color_display_stack_get_filters:
+ * @stack: a #GimpColorDisplayStack
+ *
+ * Gets the list of added color modules.
+ *
+ * Returns: (transfer none) (element-type GimpColorDisplay):
+            the list of @stack's display color modules.
+ *
+ * Since: 3.0
+ **/
 GList *
 gimp_color_display_stack_get_filters (GimpColorDisplayStack *stack)
 {
@@ -216,6 +255,15 @@ gimp_color_display_stack_get_filters (GimpColorDisplayStack *stack)
   return GET_PRIVATE (stack)->filters;
 }
 
+/**
+ * gimp_color_display_stack_add:
+ * @stack:   a #GimpColorDisplayStack
+ * @display: (transfer none): a #GimpColorDisplay
+ *
+ * Add the color module @display to @stack.
+ *
+ * Since: 1.3.23
+ **/
 void
 gimp_color_display_stack_add (GimpColorDisplayStack *stack,
                               GimpColorDisplay      *display)
@@ -244,6 +292,15 @@ gimp_color_display_stack_add (GimpColorDisplayStack *stack,
   gimp_color_display_stack_changed (stack);
 }
 
+/**
+ * gimp_color_display_stack_remove:
+ * @stack:   a #GimpColorDisplayStack
+ * @display: (transfer none): a #GimpColorDisplay
+ *
+ * Remove the color module @display from @stack.
+ *
+ * Since: 1.3.23
+ **/
 void
 gimp_color_display_stack_remove (GimpColorDisplayStack *stack,
                                  GimpColorDisplay      *display)
@@ -268,6 +325,15 @@ gimp_color_display_stack_remove (GimpColorDisplayStack *stack,
   g_object_unref (display);
 }
 
+/**
+ * gimp_color_display_stack_reorder_up:
+ * @stack:   a #GimpColorDisplayStack
+ * @display: a #GimpColorDisplay
+ *
+ * Move the color module @display up in the filter list of @stack.
+ *
+ * Since: 1.3.23
+ **/
 void
 gimp_color_display_stack_reorder_up (GimpColorDisplayStack *stack,
                                      GimpColorDisplay      *display)
@@ -296,6 +362,15 @@ gimp_color_display_stack_reorder_up (GimpColorDisplayStack *stack,
     }
 }
 
+/**
+ * gimp_color_display_stack_reorder_down:
+ * @stack:   a #GimpColorDisplayStack
+ * @display: a #GimpColorDisplay
+ *
+ * Move the color module @display down in the filter list of @stack.
+ *
+ * Since: 1.3.23
+ **/
 void
 gimp_color_display_stack_reorder_down (GimpColorDisplayStack *stack,
                                        GimpColorDisplay      *display)
diff --git a/libgimpwidgets/gimpcolornotebook.c b/libgimpwidgets/gimpcolornotebook.c
index 72b4a42c9c..5b77004e04 100644
--- a/libgimpwidgets/gimpcolornotebook.c
+++ b/libgimpwidgets/gimpcolornotebook.c
@@ -568,7 +568,7 @@ gimp_color_notebook_get_notebook (GimpColorNotebook *notebook)
  * gimp_color_notebook_get_selectors:
  * @notebook:  A #GimpColorNotebook widget.
  *
- * Return value: (element-type GimpColorSelector) (transfer-none): The
+ * Return value: (element-type GimpColorSelector) (transfer none): The
  *               notebook's list of #GimpColorSelector's.
  *
  * Since: 3.0
diff --git a/libgimpwidgets/gimpwidgetsutils.c b/libgimpwidgets/gimpwidgetsutils.c
index 840c6c76fc..4ea74cdf1d 100644
--- a/libgimpwidgets/gimpwidgetsutils.c
+++ b/libgimpwidgets/gimpwidgetsutils.c
@@ -581,6 +581,17 @@ gimp_monitor_get_color_profile (GdkMonitor *monitor)
   return profile;
 }
 
+/**
+ * gimp_widget_get_color_profile:
+ * @monitor: a #GdkMonitor
+ *
+ * This function returns the #GimpColorProfile of the monitor @widget is
+ * currently displayed on, or %NULL if there is no profile configured.
+ *
+ * Since: 3.0
+ *
+ * Return value: (transfer full): @widget's monitor's #GimpColorProfile, or %NULL.
+ **/
 GimpColorProfile *
 gimp_widget_get_color_profile (GtkWidget *widget)
 {