From 1ac05630b8598221e0770c228bef92efad9153fe Mon Sep 17 00:00:00 2001 From: ncn Date: Thu, 12 Aug 2004 12:14:01 +0000 Subject: [PATCH] Some new docs, some cleanup, some more groups. SVN revision: 11203 --- .../src/lib/canvas/evas_object_gradient.c | 57 ++++--- .../evas/src/lib/canvas/evas_object_image.c | 80 ++++++--- legacy/evas/src/lib/canvas/evas_object_text.c | 51 +++--- legacy/evas/src/lib/data/evas_hash.c | 153 ++++++++---------- 4 files changed, 192 insertions(+), 149 deletions(-) diff --git a/legacy/evas/src/lib/canvas/evas_object_gradient.c b/legacy/evas/src/lib/canvas/evas_object_gradient.c index 24239b5768..13df6efd11 100644 --- a/legacy/evas/src/lib/canvas/evas_object_gradient.c +++ b/legacy/evas/src/lib/canvas/evas_object_gradient.c @@ -56,10 +56,18 @@ static Evas_Object_Func object_func = /* it has no other api calls as all properties are standard */ /** - * To be documented. + * @defgroup Evas_Object_Gradient_Group Evas Gradient Object Functions * - * FIXME: To be fixed. - * + * Functions that work on evas gradient objects. + * + * The following example shows how + */ + +/** + * Adds a gradient object to the given evas. + * @param e The given evas. + * @return A new evas gradient object if successful. Otherwise, @c NULL. + * @ingroup Evas_Object_Gradient_Group */ Evas_Object * evas_object_gradient_add(Evas *e) @@ -76,10 +84,23 @@ evas_object_gradient_add(Evas *e) } /** - * To be documented. + * Adds a colour to the given evas gradient object. * - * FIXME: To be fixed. - * + * The @p distance parameter determines the proportion of the gradient + * object that is to be set to this colour. For instance, if red is + * added with @p distance set to 2, and green is added with @p + * distance set to 1, two-thirds will be red or reddish and one-third + * will be green or greenish. + * + * Colours are added from the top downwards. + * + * @param obj The given evas gradient object. + * @param r Red component of the given colour. + * @param g Green component of the given colour. + * @param b Blue component of the given colour. + * @param a Alpha component of the given colour. + * @param distance Proportion of the gradient object that is this colour. + * @ingroup Evas_Object_Gradient_Group */ void evas_object_gradient_color_add(Evas_Object *obj, int r, int g, int b, int a, int distance) @@ -104,10 +125,8 @@ evas_object_gradient_color_add(Evas_Object *obj, int r, int g, int b, int a, int } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Deletes all colours set for the given evas gradient object. + * @param obj The given evas gradient object. */ void evas_object_gradient_colors_clear(Evas_Object *obj) @@ -130,10 +149,11 @@ evas_object_gradient_colors_clear(Evas_Object *obj) } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Sets the angle at which the given evas gradient object sits clockwise + * from vertical. + * @param obj The given evas gradient object. + * @param angle Angle in degrees. Can be negative. + * @ingroup Evas_Object_Gradient */ void evas_object_gradient_angle_set(Evas_Object *obj, Evas_Angle angle) @@ -154,10 +174,11 @@ evas_object_gradient_angle_set(Evas_Object *obj, Evas_Angle angle) } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Retrieves the angle at which the given evas gradient object sits + * clockwise from the vertical. + * @param obj The given evas gradient object. + * @return The current angle if successful. @c 0.0 otherwise. + * @ingroup Evas_Object_Gradient */ Evas_Angle evas_object_gradient_angle_get(Evas_Object *obj) diff --git a/legacy/evas/src/lib/canvas/evas_object_image.c b/legacy/evas/src/lib/canvas/evas_object_image.c index 1d5274d1bc..9bf642f398 100644 --- a/legacy/evas/src/lib/canvas/evas_object_image.c +++ b/legacy/evas/src/lib/canvas/evas_object_image.c @@ -105,12 +105,18 @@ evas_object_image_add(Evas *e) return obj; } +/** + * @defgroup Evas_Object_Image_File_Group Image Object File Functions + * + * Functions that write to or retrieve images from files. + */ + /** * Sets the image displayed by the given image object. * @param obj The given image object. * @param file Name of the file that the image exists in. * @param key Can be NULL. - * @ingroup Evas_Object_Image + * @ingroup Evas_Object_Image_File_Group */ void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key) @@ -176,7 +182,7 @@ evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key) * name in. * @param key Pointer to a character pointer to store the pointer to the key * string in. - * @ingroup Evas_Object_Image + * @ingroup Evas_Object_Image_File_Group */ void evas_object_image_file_get(Evas_Object *obj, char **file, char **key) @@ -198,6 +204,12 @@ evas_object_image_file_get(Evas_Object *obj, char **file, char **key) if (key) *key = o->cur.key; } +/** + * @defgroup Evas_Object_Image_Border_Group Image Object Border Functions + * + * Functions that adjust the unscaled image border of image objects. + */ + /** * Sets how much of each border of the given evas image object is not * to be scaled. @@ -215,7 +227,7 @@ evas_object_image_file_get(Evas_Object *obj, char **file, char **key) * @param r Distance of the right border that is not to be stretched. * @param t Distance of the top border that is not to be stretched. * @param b Distance of the bottom border that is not to be stretched. - * @ingroup Evas_Object_Image + * @ingroup Evas_Object_Image_Border_Group */ void evas_object_image_border_set(Evas_Object *obj, int l, int r, int t, int b) @@ -259,7 +271,7 @@ evas_object_image_border_set(Evas_Object *obj, int l, int r, int t, int b) * @param r Pointer to an integer to store the right border width in. * @param t Pointer to an integer to store the top border width in. * @param b Pointer to an integer to store the bottom border width in. - * @ingroup Evas_Object_Image + * @ingroup Evas_Object_Image_Border_Group */ void evas_object_image_border_get(Evas_Object *obj, int *l, int *r, int *t, int *b) @@ -287,6 +299,13 @@ evas_object_image_border_get(Evas_Object *obj, int *l, int *r, int *t, int *b) if (b) *b = o->cur.border.b; } +/** + * @defgroup Evas_Object_Image_Fill_Group Image Object Fill Rectangle Functions + * + * Functions that deal with what areas of the image object are to be + * tiled with the given image. + */ + /** * Sets the rectangle on the image object that the image will be drawn * to. @@ -299,11 +318,12 @@ evas_object_image_border_get(Evas_Object *obj, int *l, int *r, int *t, int *b) * The default values for the fill parameters is @p x = 0, @p y = 0, * @p w = 32 and @p h = 32. * - * @param obj The given evas image object. - * @param x The X coordinate for the top left corner of the image. - * @param y The Y coordinate for the top left corner of the image. - * @param w The width of the image. - * @param h The height of the image. + * @param obj The given evas image object. + * @param x The X coordinate for the top left corner of the image. + * @param y The Y coordinate for the top left corner of the image. + * @param w The width of the image. + * @param h The height of the image. + * @ingroup Evas_Object_Image_Fill_Group */ void evas_object_image_fill_set(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) @@ -339,11 +359,12 @@ evas_object_image_fill_set(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Co * * See @ref evas_object_image_fill_set for more details. * - * @param obj The given evas image object. - * @param x Pointer to an integer to store the X coordinate in. - * @param y Pointer to an integer to store the Y coordinate in. - * @param w Pointer to an integer to store the width in. - * @param h Pointer to an integer to store the height in. + * @param obj The given evas image object. + * @param x Pointer to an integer to store the X coordinate in. + * @param y Pointer to an integer to store the Y coordinate in. + * @param w Pointer to an integer to store the width in. + * @param h Pointer to an integer to store the height in. + * @ingroup Evas_Object_Image_Fill_Group */ void evas_object_image_fill_get(Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) @@ -372,10 +393,24 @@ evas_object_image_fill_get(Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_ } /** - * To be documented. + * @defgroup Evas_Object_Image_Size Image Object Image Size Functions * - * FIXME: To be fixed. - * + * Functions that change the size of the image used by an image object. + */ + +/** + * Sets the size of the image to be display by the given image object. + * + * This function will scale down or crop the image so that it is + * treated as if it were at the given size. If the size given is + * smaller than the image, it will be cropped. If the size given is + * larger, then the image will be treated as if it were in the upper + * left hand corner of a larger image that is otherwise transparent. + * + * @param obj The given image object. + * @param w The new width. + * @param h The new height. + * @ingroup Evas_Object_Image_Size */ void evas_object_image_size_set(Evas_Object *obj, int w, int h) @@ -415,11 +450,12 @@ evas_object_image_size_set(Evas_Object *obj, int w, int h) /** * Retrieves the size of the image displayed by the given image object. - * @param obj The given image object. - * @param w A pointer to an integer in which to store the width. Can be - * @c NULL. - * @param h A pointer to an integer in which to store the height. Can be - * @c NULL. + * @param obj The given image object. + * @param w A pointer to an integer in which to store the width. Can be + * @c NULL. + * @param h A pointer to an integer in which to store the height. Can be + * @c NULL. + * @ingroup Evas_Object_Image_Size */ void evas_object_image_size_get(Evas_Object *obj, int *w, int *h) diff --git a/legacy/evas/src/lib/canvas/evas_object_text.c b/legacy/evas/src/lib/canvas/evas_object_text.c index 53912137ba..395144cb0a 100644 --- a/legacy/evas/src/lib/canvas/evas_object_text.c +++ b/legacy/evas/src/lib/canvas/evas_object_text.c @@ -745,10 +745,9 @@ evas_object_text_font_get(Evas_Object *obj, char **font, Evas_Font_Size *size) } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Sets the text to be displayed by the given evas text object. + * @param obj Evas text object. + * @param text Text to display. */ void evas_object_text_text_set(Evas_Object *obj, const char *text) @@ -805,10 +804,9 @@ evas_object_text_text_set(Evas_Object *obj, const char *text) } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Retrieves the text currently being displayed by the given evas text object. + * @param obj The given evas text object. + * @return The text currently being displayed. Do not free it. */ const char * evas_object_text_text_get(Evas_Object *obj) @@ -1096,13 +1094,16 @@ evas_object_text_char_coords_get(Evas_Object *obj, Evas_Coord x, Evas_Coord y, E } - +/** + * @defgroup Evas_Font_Path_Group Font Path Functions + * + * Functions that edit the paths being used to load fonts. + */ /** - * To be documented. - * - * FIXME: To be fixed. - * + * Removes all font paths loaded into memory for the given evas. + * @param e The given evas. + * @ingroup Evas_Font_Path_Group */ void evas_font_path_clear(Evas *e) @@ -1118,10 +1119,10 @@ evas_font_path_clear(Evas *e) } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Appends a font path to the list of font paths used by the given evas. + * @param e The given evas. + * @param path The new font path. + * @ingroup Evas_Font_Path_Group */ void evas_font_path_append(Evas *e, const char *path) @@ -1134,10 +1135,10 @@ evas_font_path_append(Evas *e, const char *path) } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Prepends a font path to the list of font paths used by the given evas. + * @param e The given evas. + * @param path The new font path. + * @ingroup Evas_Font_Path_Group */ void evas_font_path_prepend(Evas *e, const char *path) @@ -1150,10 +1151,10 @@ evas_font_path_prepend(Evas *e, const char *path) } /** - * To be documented. - * - * FIXME: To be fixed. - * + * Retrieves the list of font paths used by the given evas. + * @param e The given evas. + * @return The list of font paths used. + * @ingroup Evas_Font_Path_Group */ const Evas_List * evas_font_path_list(Evas *e) diff --git a/legacy/evas/src/lib/data/evas_hash.c b/legacy/evas/src/lib/data/evas_hash.c index f304715e99..2da8233969 100644 --- a/legacy/evas/src/lib/data/evas_hash.c +++ b/legacy/evas/src/lib/data/evas_hash.c @@ -21,29 +21,12 @@ evas_hash_gen(const char *key) } /** - * Add an entry to the hash table. - * @param hash The hash table handle to hold the entry - * @param key The key string for the entry - * @param data The pointer to the data to be stored - * @return The modified hash table handle - * - * This function takes the data pointed to by @p data and inserts it into the - * hash table @p hash, under the string key @p key. It will return a modified - * hash table handle when done. An empty hash table starts as a NULL pointer. - * - * It is expected that the @p key will be a unique string within the hash table - * otherwise it is not deterministic as to which inserted data pointer will be - * returned when evas_hash_find() is called, or which one wil be removed on - * evas_hash_del() being called. A @p key of NULL is allowed, but will mean - * unique lookups are impossible (unless the entry is the only one with a NULL - * key in the hash table). Key strings are casesensitive. - * - * If a memory allocation failure occurs, the old hash table pointer will be - * returned, with the hash table contents unchanged, and the programmer should - * use evas_hash_alloc_error() to determine if an allocation error occured and - * recover from this situation. - * - * Example: + * @defgroup Evas_Hash_Data Hash Data Functions + * + * Functions that add, access or remove data from hashes. + * + * The following example shows how to add and then access data in a + * hash table: * @code * Evas_Hash *hash = NULL; * extern void *my_data; @@ -59,6 +42,45 @@ evas_hash_gen(const char *key) * printf("My Data inserted and successfully found.\n"); * } * @endcode + * + * What follows is another example, showing how the @ref evas_hash_del + * function is used: + * @code + * extern Evas_Hash *hash; + * extern void *data; + * + * printf("Insert some data...\n"); + * hash = evas_hash_add(hash, "My Data", my_data); + * printf("Removing by key...\n"); + * hash = evas_hash_del(hash, "My Data", NULL); + * printf("Insert some more data as a NULL key...\n"); + * hash = evas_hash_add(hash, NULL, my_data); + * printf("Removing by data as a NULL key...\n"); + * hash = evas_hash_del(hash, NULL, my_data); + * @endcode + */ + +/** + * Adds an entry to the given hash table. + * + * @p key is expected to be a unique string within the hash table. + * Otherwise, you cannot be sure which inserted data pointer will be + * accessed with @ref evas_hash_find , and removed with + * @ref evas_hash_del . + * + * Key strings are case sensitive. + * + * @ref evas_hash_alloc_error should be used to determine if an + * allocation error occurred during this function. + * + * @param hash The given hash table. Can be @c NULL, in which case a + * new hash table is allocated and returned. + * @param key A unique string. Can be @c NULL. + * @param data Data to associate with the string given by @p key. + * @return Either the given hash table, or if the given value for @p + * hash is @c NULL, then a new one. @c NULL will be returned + * if memory could not be allocated for a new table. + * @ingroup Evas_Hash_Data */ Evas_Hash * evas_hash_add(Evas_Hash *hash, const char *key, const void *data) @@ -116,35 +138,19 @@ evas_hash_add(Evas_Hash *hash, const char *key, const void *data) } /** - * Remove an entry from the hash table - * @param hash The hash table handle to remove the entry from - * @param key The key string for the entry - * @param data The pointer to the data to be removed - * @return The modified hash table handle - * - * This function removed an entry from the hash table pointed to by @p hash. - * The key is identified by its string @p key. If the @p key is NULL, then the - * data pointer @p data must be provided for a match to be possible so the - * entry can be removed. As long as the @p key is not NULL, the @p data pointer - * is not required and can be NULL. Remember than key strings are case - * sensitive. - * - * This function returns the modified hash table after removal. - * - * Example: - * @code - * extern Evas_Hash *hash; - * extern void *data; - * - * printf("Insert some data...\n"); - * hash = evas_hash_add(hash, "My Data", my_data); - * printf("Removing by key...\n"); - * hash = evas_hash_del(hash, "My Data", NULL); - * printf("Insert some more data as a NULL key...\n"); - * hash = evas_hash_add(hash, NULL, my_data); - * printf("Removing by data as a NULL key...\n"); - * hash = evas_hash_del(hash, NULL, my_data); - * @endcode + * Removes the entry identified by @p key or @p data from the given + * hash table. + * + * If @p key is @c NULL, then @p data is used to find a match to + * remove. + * + * @param hash The given hash table. + * @param key The key string. Can be @c NULL. + * @param data The data pointer to remove if @p key is @c NULL. + * Otherwise, not required and can be @c NULL. + * @return The modified hash table. If there are no entries left, the + * hash table will be freed and @c NULL will be returned. + * @ingroup Evas_Hash_Data */ Evas_Hash * evas_hash_del(Evas_Hash *hash, const char *key, const void *data) @@ -177,26 +183,12 @@ evas_hash_del(Evas_Hash *hash, const char *key, const void *data) } /** - * Find a specified entry in a hash table - * @param hash The hash table handle to find the entry in - * @param key The key string for the entry - * @return The data pointer for the stored entry, or NULL if not found. - * - * This function finds an entry by its @p key, which is case sensitive. If the - * entry in the hash table @p hash is found, the data pointer that was stored - * under than entry is returned, otherwise NULL is returned. - * - * Example: - * @code - * extern Evas_Hash *hash; - * extern void *data; - * - * hash = evas_hash_add(hash, "My Data", my_data); - * if (evas_hash_find(hash, "My Data") == my_data) - * { - * printf("Found stored entry!\n"); - * } - * @endcode + * Retrieves a specific entry in the given hash table. + * @param hash The given hash table. + * @param key The key string of the entry to find. + * @return The data pointer for the stored entry, or @c NULL if not + * found. + * @ingroup Evas_Hash_Data */ void * evas_hash_find(Evas_Hash *hash, const char *key) @@ -232,18 +224,9 @@ evas_hash_find(Evas_Hash *hash, const char *key) } /** - * Return the number of buckets in the hash table - * @param hash The hash table to return the bucket count of - * @return The number of buckets in the hash table - * - * This function returns the number of buckes in he hash table @p hash. - * - * Example: - * @code - * extern Evas_Hash *hash; - * - * printf("Hash bucket count: %i\n", evas_hash_size(hash)); - * @endcode + * Retrieves the number of buckets available in the given hash table. + * @param hash The given hash table. + * @return @c 256 if @p hash is not @c NULL. @c 0 otherwise. */ int evas_hash_size(Evas_Hash *hash) @@ -252,6 +235,8 @@ evas_hash_size(Evas_Hash *hash) return 256; } +/** @todo Complete documenting evas_hash.c */ + /** * Free an entire hash table * @param hash The hash table to be freed