From d443584880e3905ef7ee7cd88e58534803bfc928 Mon Sep 17 00:00:00 2001 From: Bill Haneman Date: Mon, 30 Apr 2001 12:01:41 +0000 Subject: [PATCH] Improved gtk-doc comments. --- atk/atkimage.c | 98 ++++++++++++++++++++++++++++++++-------------------------- atk/atktable.c | 27 +++++++--------- 2 files changed, 67 insertions(+), 58 deletions(-) diff --git a/atk/atkimage.c b/atk/atkimage.c index 4736c50..863210e 100755 --- a/atk/atkimage.c +++ b/atk/atkimage.c @@ -17,7 +17,6 @@ * Boston, MA 02111-1307, USA. */ -/* Superseded by atkimage.c */ #include "atkimage.h" GType @@ -42,14 +41,11 @@ atk_image_get_type () /** * atk_image_get_storage_type: - * @value: a GObject instance that implements AtkImageIface - * @return: a AtkStorageType representing the image storage type, or 0 - * if value does not implement this interface. + * @obj: a GObject instance that implements AtkImageIface + * return values: a AtkStorageType representing the image storage type + * + * [maybe this method will be replaced, watch this space.] * - * WARNING: callers should not rely on %NULL or on a zero value for - * indication of whether AtkImageIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_image() convenience method. **/ AtkImageType atk_image_get_storage_type (AtkImage *obj) @@ -62,21 +58,21 @@ atk_image_get_storage_type (AtkImage *obj) iface = ATK_IMAGE_GET_IFACE (obj); if (iface->get_storage_type) - return (iface->get_storage_type) (obj); + { + return (iface->get_storage_type) (obj); + } else - return 0; + { + return 0; + } } /** * atk_image_get_image_description: - * @value: a GObject instance that implements AtkImageIface - * @return: a gchar* representing the image description, or NULL - * if value does not implement this interface. + * @obj: a GObject instance that implements AtkImageIface + * return values: a gchar* representing the image description * - * WARNING: callers should not rely on %NULL or on a zero value for - * indication of whether AtkImageIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_image() convenience method. + * Get a textual description of this image. **/ G_CONST_RETURN gchar* atk_image_get_image_description (AtkImage *obj) @@ -89,21 +85,22 @@ atk_image_get_image_description (AtkImage *obj) iface = ATK_IMAGE_GET_IFACE (obj); if (iface->get_image_description) - return (iface->get_image_description) (obj); + { + return (iface->get_image_description) (obj); + } else - return NULL; + { + return NULL; + } } /** * atk_image_get_image_height: - * @value: a GObject instance that implements AtkImageIface - * @return: a gint representing the image height, or 0 - * if value does not implement this interface. + * @obj: a GObject instance that implements AtkImageIface + * return values: a gint representing the image height in pixel coords + * + * Get the height, in pixels/screen coords, of this image. * - * WARNING: callers should not rely on %NULL or on a zero value for - * indication of whether AtkImageIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_image() convenience method. **/ gint atk_image_get_image_height (AtkImage *obj) @@ -116,21 +113,22 @@ atk_image_get_image_height (AtkImage *obj) iface = ATK_IMAGE_GET_IFACE (obj); if (iface->get_image_height) - return (iface->get_image_height) (obj); + { + return (iface->get_image_height) (obj); + } else - return 0; + { + return 0; + } } /** * atk_image_get_image_width: - * @value: a GObject instance that implements AtkImageIface - * @return: a gint representing the image width, or 0 - * if value does not implement this interface. + * @obj: a GObject instance that implements AtkImageIface + * return values: a gint representing the image width + * + * Get the width, in pixel/screen coords, of this image. * - * WARNING: callers should not rely on %NULL or on a zero value for - * indication of whether AtkImageIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_image() convenience method. **/ gint atk_image_get_image_width (AtkImage *obj) @@ -143,27 +141,41 @@ atk_image_get_image_width (AtkImage *obj) iface = ATK_IMAGE_GET_IFACE (obj); if (iface->get_image_width) - return (iface->get_image_width) (obj); + { + return (iface->get_image_width) (obj); + } else - return 0; + { + return 0; + } } /** * atk_image_set_image_description: - * @value: a GObject instance that implements AtkImageIface - * @return: void + * @obj: a GObject instance that implements AtkImageIface + * return values: boolean TRUE, or FALSE if operation could + * not be completed. + * + * Sets the textual description for this image. + * **/ -void +gboolean atk_image_set_image_description (AtkImage *obj, const gchar *description) { AtkImageIface *iface; - g_return_if_fail (obj != NULL); - g_return_if_fail (ATK_IS_IMAGE (obj)); + g_return_val_if_fail (obj != NULL, FALSE); + g_return_val_if_fail (ATK_IS_IMAGE (obj), FALSE); iface = ATK_IMAGE_GET_IFACE (obj); if (iface->set_image_description) - (iface->set_image_description) (obj, description); + { + return (iface->set_image_description) (obj, description); + } + else + { + return FALSE; + } } diff --git a/atk/atktable.c b/atk/atktable.c index 5394321..06a435a 100755 --- a/atk/atktable.c +++ b/atk/atktable.c @@ -41,14 +41,11 @@ atk_table_get_type () /** * atk_table_ref_at: - * @value: a GObject instance that implements AtkTableIface - * @return: a AtkObject* representing the referred to accessible , or NULL - * if value does not implement this interface. + * @obj: a GObject instance that implements AtkTableIface + * return values: a AtkObject* representing the referred to accessible + * + * Get a reference to the table cell at #row, #column * - * WARNING: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. **/ AtkObject* atk_table_ref_at (AtkTable *obj, @@ -432,7 +429,7 @@ atk_table_get_summary (AtkTable *obj) /** * atk_table_get_selected_rows: * @value: a GObject instance that implements AtkTableIface - * @return: a gint* representing the selected rows, + * @return: a gint* representing the selected rows, * or NULL if value does not implement this interface. * * WARNING: callers should not rely on %NULL or on a zero value for @@ -459,7 +456,7 @@ atk_table_get_selected_rows (AtkTable *obj) /** * atk_table_get_selected_columns: * @value: a GObject instance that implements AtkTableIface - * @return: a gint* representing the selected columns, + * @return: a gint* representing the selected columns, * or NULL if value does not implement this interface. * * WARNING: callers should not rely on %NULL or on a zero value for @@ -571,7 +568,7 @@ atk_table_is_selected (AtkTable *obj, /** * atk_table_set_caption: * @value: a GObject instance that implements AtkTableIface - * @return: void + * @return: void **/ void atk_table_set_caption (AtkTable *obj, @@ -591,7 +588,7 @@ atk_table_set_caption (AtkTable *obj, /** * atk_table_set_column_description: * @value: a GObject instance that implements AtkTableIface - * @return: void + * @return: void **/ void atk_table_set_column_description (AtkTable *obj, @@ -612,7 +609,7 @@ atk_table_set_column_description (AtkTable *obj, /** * atk_table_set_column_header: * @value: a GObject instance that implements AtkTableIface - * @return: void + * @return: void **/ void atk_table_set_column_header (AtkTable *obj, @@ -633,7 +630,7 @@ atk_table_set_column_header (AtkTable *obj, /** * atk_table_set_row_description: * @value: a GObject instance that implements AtkTableIface - * @return: void + * @return: void **/ void atk_table_set_row_description (AtkTable *obj, @@ -654,7 +651,7 @@ atk_table_set_row_description (AtkTable *obj, /** * atk_table_set_row_header: * @value: a GObject instance that implements AtkTableIface - * @return: void + * @return: void **/ void atk_table_set_row_header (AtkTable *obj, @@ -675,7 +672,7 @@ atk_table_set_row_header (AtkTable *obj, /** * atk_table_set_summary: * @value: a GObject instance that implements AtkTableIface - * @return: void + * @return: void **/ void atk_table_set_summary (AtkTable *obj, -- 2.7.4