Add annotations and fix documentation syntax warnings

6 files changed, 70 insertions, 36 deletions

diff --git a/libmate-desktop/mate-aboutdialog.c b/libmate-desktop/mate-aboutdialog.c
index 6bf60a6..45b223c 100644
--- a/libmate-desktop/mate-aboutdialog.c
+++ b/libmate-desktop/mate-aboutdialog.c
@@ -37,8 +37,7 @@
 #include <glib/gi18n-lib.h>
 
 
-/**
- * The #MateAboutDialog offers a simple way to display information about
+/* The #MateAboutDialog offers a simple way to display information about
  * a program like its logo, name, copyright, website and license. It is
  * also possible to give credits to the authors, documenters, translators
  * and artists who have worked on the program. An about dialog is typically
@@ -814,7 +813,8 @@ mate_about_dialog_show (GtkWidget *widget)
  * Return value: The program name. The string is owned by the about
  *  dialog and must not be modified.
  *
- * Since: 1.9 */
+ * Since: 1.9
+ */
 const gchar *
 mate_about_dialog_get_program_name (MateAboutDialog *about)
 {
@@ -959,7 +959,7 @@ mate_about_dialog_get_copyright (MateAboutDialog *about)
 /**
  * mate_about_dialog_set_copyright:
  * @about: a #MateAboutDialog
- * @copyright: (allow-none) the copyright string
+ * @copyright: (allow-none): the copyright string
  *
  * Sets the copyright string to display in the about dialog.
  * This should be a short string of one or two lines.
@@ -2243,7 +2243,7 @@ close_cb (MateAboutDialog *about)
  * gtk_show_about_dialog:
  * @parent: (allow-none): transient parent, or %NULL for none
  * @first_property_name: the name of the first property
- * @Varargs: value of first property, followed by more properties, %NULL-terminated
+ * @...: value of first property, followed by more properties, %NULL-terminated
  *
  * This is a convenience function for showing an application's about box.
  * The constructed dialog is associated with the parent window and
diff --git a/libmate-desktop/mate-bg.c b/libmate-desktop/mate-bg.c
index beb0e90..4c45821 100644
--- a/libmate-desktop/mate-bg.c
+++ b/libmate-desktop/mate-bg.c
@@ -1149,7 +1149,7 @@ mate_bg_get_pixmap_size (MateBG   *bg,
  * @window:
  * @width:
  * @height:
- * @is_root:
+ * @root:
  *
  * Create a surface that can be set as background for @window. If @is_root is
  * TRUE, the surface created will be created by a temporary X server connection
@@ -1166,7 +1166,7 @@ mate_bg_create_pixmap  (MateBG      *bg,
 		 	GdkWindow   *window,
 			int	     width,
 			int	     height,
-			gboolean     is_root)
+			gboolean     root)
 {
 	int pm_width, pm_height;
 
@@ -1187,7 +1187,7 @@ mate_bg_create_pixmap  (MateBG      *bg,
 	mate_bg_get_pixmap_size (bg, width, height, &pm_width, &pm_height);
 
 
-	if (is_root)
+	if (root)
 	{
 		surface = make_root_pixmap (window, pm_width, pm_height);
 	}
@@ -1211,7 +1211,7 @@ mate_bg_create_pixmap  (MateBG      *bg,
 
 		pixbuf = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8,
 					 width, height);
-		mate_bg_draw (bg, pixbuf, gdk_window_get_screen (window), is_root);
+		mate_bg_draw (bg, pixbuf, gdk_window_get_screen (window), root);
 		gdk_cairo_set_source_pixbuf (cr, pixbuf, 0, 0);
 		g_object_unref (pixbuf);
 	}
diff --git a/libmate-desktop/mate-desktop-utils.c b/libmate-desktop/mate-desktop-utils.c
index df7aa3f..6043f36 100644
--- a/libmate-desktop/mate-desktop-utils.c
+++ b/libmate-desktop/mate-desktop-utils.c
@@ -58,14 +58,14 @@ hls_to_rgb (gdouble *h,
  * @argc: a pointer to the vector size
  * @argv: a pointer to the vector
  *
- * Description:  Prepends a terminal (either the one configured as default in
- * the user's MATE setup, or one of the common xterm emulators) to the passed
- * in vector, modifying it in the process.  The vector should be allocated with
- * #g_malloc, as this will #g_free the original vector.  Also all elements must
- * have been allocated separately.  That is the standard glib/MATE way of
- * doing vectors however.  If the integer that @argc points to is negative, the
- * size will first be computed.  Also note that passing in pointers to a vector
- * that is empty, will just create a new vector for you.
+ * Prepends a terminal (either the one configured as default in the user's
+ * MATE setup, or one of the common xterm emulators) to the passed in vector,
+ * modifying it in the process.  The vector should be allocated with #g_malloc,
+ * as this will #g_free the original vector.  Also all elements must have been
+ * allocated separately.  That is the standard glib/MATE way of doing vectors
+ * however.  If the integer that @argc points to is negative, the size will
+ * first be computed.  Also note that passing in pointers to a vector that is
+ * empty, will just create a new vector for you.
  **/
 void
 mate_desktop_prepend_terminal_to_vector (int *argc, char ***argv)
@@ -245,13 +245,14 @@ _mate_desktop_init_i18n (void) {
 #if GTK_CHECK_VERSION (3, 0, 0)
 
 /**
+ * gtk_style_shade:
+ * @a:  the starting colour
+ * @b:  [out] the resulting colour
+ * @k:  amount to scale lightness and saturation by
+ *
  * Takes a colour "a", scales the lightness and saturation by a certain amount,
  * and sets "b" to the resulting colour.
  * gtkstyle.c cut-and-pastage.
- *
- * \param a  the starting colour
- * \param b  [out] the resulting colour
- * \param k  amount to scale lightness and saturation by
  */
 static void
 gtk_style_shade (GdkRGBA *a,
@@ -288,11 +289,12 @@ gtk_style_shade (GdkRGBA *a,
 }
 
 /**
- * Converts a red/green/blue triplet to a hue/lightness/saturation triplet.
+ * rgb_to_hls:
+ * @r:  on input, red; on output, hue
+ * @g:  on input, green; on output, lightness
+ * @b:  on input, blue; on output, saturation
  *
- * \param r  on input, red; on output, hue
- * \param g  on input, green; on output, lightness
- * \param b  on input, blue; on output, saturation
+ * Converts a red/green/blue triplet to a hue/lightness/saturation triplet.
  */
 static void
 rgb_to_hls (gdouble *r,
@@ -366,11 +368,12 @@ rgb_to_hls (gdouble *r,
 }
 
 /**
- * Converts a hue/lightness/saturation triplet to a red/green/blue triplet.
+ * hls_to_rgb:
+ * @h: on input, hue; on output, red
+ * @l: on input, lightness; on output, green
+ * @s  on input, saturation; on output, blue
  *
- * \param h  on input, hue; on output, red
- * \param l  on input, lightness; on output, green
- * \param s  on input, saturation; on output, blue
+ * Converts a hue/lightness/saturation triplet to a red/green/blue triplet.
  */
 static void
 hls_to_rgb (gdouble *h,
diff --git a/libmate-desktop/mate-rr-labeler.c b/libmate-desktop/mate-rr-labeler.c
index f7a2035..e65ced5 100644
--- a/libmate-desktop/mate-rr-labeler.c
+++ b/libmate-desktop/mate-rr-labeler.c
@@ -511,6 +511,17 @@ setup_from_config (MateRRLabeler *labeler)
 	create_label_windows (labeler);
 }
 
+/**
+ * mate_rr_labeler_new:
+ * @config: Configuration of the screens to label
+ *
+ * Create a GUI element that will display colored labels on each connected monitor.
+ * This is useful when users are required to identify which monitor is which, e.g. for
+ * for configuring multiple monitors.
+ * The labels will be shown by default, use mate_rr_labeler_hide to hide them.
+ *
+ * Returns: A new #GnomeRRLabeler
+ */
 MateRRLabeler *
 mate_rr_labeler_new (MateRRConfig *config)
 {
@@ -519,6 +530,12 @@ mate_rr_labeler_new (MateRRConfig *config)
 	return g_object_new (MATE_TYPE_RR_LABELER, "config", config, NULL);
 }
 
+/**
+ * mate_rr_labeler_hide:
+ * @labeler: A #MateRRLabeler
+ *
+ * Hide ouput labels.
+ */
 void
 mate_rr_labeler_hide (MateRRLabeler *labeler)
 {
@@ -542,6 +559,14 @@ mate_rr_labeler_hide (MateRRLabeler *labeler)
 }
 
 #if GTK_CHECK_VERSION (3, 0, 0)
+/**
+ * mate_rr_labeler_get_rgba_for_output:
+ * @labeler: A #MateRRLabeler
+ * @output: Output device (i.e. monitor) to query
+ * @rgba_out: (out): Color of selected monitor.
+ *
+ * Get the color used for the label on a given output (monitor).
+ */
 void
 mate_rr_labeler_get_rgba_for_output (MateRRLabeler *labeler, MateRROutputInfo *output, GdkRGBA *color_out)
 {
@@ -569,6 +594,14 @@ mate_rr_labeler_get_rgba_for_output (MateRRLabeler *labeler, MateRROutputInfo *o
 }
 #endif
 
+/**
+ * mate_rr_labeler_get_color_for_output:
+ * @labeler: A #MateRRLabeler
+ * @output: Output device (i.e. monitor) to query
+ * @color_out: (out): Color of selected monitor.
+ *
+ * Get the color used for the label on a given output (monitor).
+ */
 void
 mate_rr_labeler_get_color_for_output (MateRRLabeler *labeler, MateRROutputInfo *output, GdkColor *color_out)
 {
diff --git a/libmate-desktop/mate-rr-output-info.c b/libmate-desktop/mate-rr-output-info.c
index 896b010..7e5a8ee 100644
--- a/libmate-desktop/mate-rr-output-info.c
+++ b/libmate-desktop/mate-rr-output-info.c
@@ -96,7 +96,6 @@ void mate_rr_output_info_set_active (MateRROutputInfo *self, gboolean active)
 
 /**
  * mate_rr_output_info_get_geometry:
- *
  * @self: a #MateRROutputInfo
  * @x: (out) (allow-none):
  * @y: (out) (allow-none):
@@ -169,7 +168,6 @@ gboolean mate_rr_output_info_is_connected (MateRROutputInfo *self)
 
 /**
  * mate_rr_output_info_get_vendor:
- *
  * @self: a #MateRROutputInfo
  * @vendor: (out caller-allocates) (array fixed-size=4):
  */
diff --git a/libmate-desktop/mate-rr.c b/libmate-desktop/mate-rr.c
index 9c435f9..921190a 100644
--- a/libmate-desktop/mate-rr.c
+++ b/libmate-desktop/mate-rr.c
@@ -850,11 +850,11 @@ mate_rr_screen_init (MateRRScreen *self)
 
 /**
  * mate_rr_screen_new:
- * Creates a new #MateRRScreen instance
- *
  * @screen: the #GdkScreen on which to operate
  * @error: will be set if XRandR is not supported
  *
+ * Creates a new #MateRRScreen instance
+ *
  * Returns: a new #MateRRScreen instance or NULL if screen could not be created,
  * for instance if the driver does not support Xrandr 1.2
  */
@@ -890,13 +890,13 @@ mate_rr_screen_set_size (MateRRScreen *screen,
 
 /**
  * mate_rr_screen_get_ranges:
- *
- * Get the ranges of the screen
  * @screen: a #MateRRScreen
  * @min_width: (out): the minimum width
  * @max_width: (out): the maximum width
  * @min_height: (out): the minimum height
  * @max_height: (out): the maximum height
+ *
+ * Get the ranges of the screen
  */
 void
 mate_rr_screen_get_ranges (MateRRScreen *screen,
@@ -1427,7 +1427,7 @@ mate_rr_output_get_edid_data (MateRROutput *output)
 }
 
 /**
- * mate_rr_screen_get_output_by_id:
+ * mate_rr_screen_get_output_by_name:
  *
  * Returns: (transfer none): the output identified by @name
  */