Add annotations and fix documentation syntax warnings

author: infirit <[email protected]> 2015-07-20 21:23:21 +0200
committer: infirit <[email protected]> 2015-07-30 00:15:48 +0200
commit: b6f2d9f8f4a82d1ddf075b2817d442f42840eb48 (patch)
tree: 18f0726a83435ccd2edd1bec40ef646dd047c724 /libmate-desktop
parent: b4af7eca1d880dd497fe8d9581905f950176378b (diff)
download: mate-desktop-b6f2d9f8f4a82d1ddf075b2817d442f42840eb48.tar.bz2
mate-desktop-b6f2d9f8f4a82d1ddf075b2817d442f42840eb48.tar.xz
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
 */
author	infirit <[email protected]>	2015-07-20 21:23:21 +0200
committer	infirit <[email protected]>	2015-07-30 00:15:48 +0200
commit	b6f2d9f8f4a82d1ddf075b2817d442f42840eb48 (patch)
tree	18f0726a83435ccd2edd1bec40ef646dd047c724 /libmate-desktop
parent	b4af7eca1d880dd497fe8d9581905f950176378b (diff)
download	mate-desktop-b6f2d9f8f4a82d1ddf075b2817d442f42840eb48.tar.bz2 mate-desktop-b6f2d9f8f4a82d1ddf075b2817d442f42840eb48.tar.xz