From b6f2d9f8f4a82d1ddf075b2817d442f42840eb48 Mon Sep 17 00:00:00 2001 From: infirit Date: Mon, 20 Jul 2015 21:23:21 +0200 Subject: Add annotations and fix documentation syntax warnings --- libmate-desktop/mate-aboutdialog.c | 10 ++++---- libmate-desktop/mate-bg.c | 8 +++---- libmate-desktop/mate-desktop-utils.c | 43 +++++++++++++++++++---------------- libmate-desktop/mate-rr-labeler.c | 33 +++++++++++++++++++++++++++ libmate-desktop/mate-rr-output-info.c | 2 -- libmate-desktop/mate-rr.c | 10 ++++---- 6 files changed, 70 insertions(+), 36 deletions(-) (limited to 'libmate-desktop') 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 -/** - * 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 */ -- cgit v1.2.1