diff --git a/ChangeLog b/ChangeLog index d9288813f..0499858c7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2005-09-02 Carl Worth + + * src/cairo-cache-private.h: + * src/cairo-cache.c: (_cairo_cache_fini): Clean up some + documentation issues pointed out by otaylor. + 2005-09-01 Keith Packard reviewed by: otaylor deserves credit for noticing a problem diff --git a/src/cairo-cache-private.h b/src/cairo-cache-private.h index a6eeba29c..a89148b45 100644 --- a/src/cairo-cache-private.h +++ b/src/cairo-cache-private.h @@ -46,9 +46,7 @@ typedef struct _cairo_cache cairo_cache_t; * * A #cairo_cache_entry_t contains both a key and a value for * cairo_cache_t. User-derived types for cairo_cache_entry_t must - * be type-compatible with this structure (eg. they must have an - * unsigned long as the first parameter. The easiest way to get this - * is to use: + * have a cairo_cache_entry_t as their first field. For example: * * typedef _my_entry { * cairo_cache_entry_t base; @@ -63,14 +61,14 @@ typedef struct _cairo_cache cairo_cache_t; * IMPORTANT: The caller is responsible for initializing * my_entry->base.hash with a hash code derived from the key. The * essential property of the hash code is that keys_equal must never - * return TRUE for two keys that have different hashes. The best hash + * return %TRUE for two keys that have different hashes. The best hash * code will reduce the frequency of two keys with the same code for - * which keys_equal returns FALSE. + * which keys_equal returns %FALSE. * * The user must also initialize my_entry->base.size to indicate * the size of the current entry. What units to use for size is * entirely up to the caller, (though the same units must be used for - * the max_size parameter passed to _cairo_cache_create). If all + * the max_size parameter passed to _cairo_cache_create()). If all * entries are close to the same size, the simplest thing to do is to * just use units of "entries", (eg. set size==1 in all entries and * set max_size to the number of entries which you want to be saved diff --git a/src/cairo-cache.c b/src/cairo-cache.c index 25a35bf8e..ffee863de 100644 --- a/src/cairo-cache.c +++ b/src/cairo-cache.c @@ -75,7 +75,7 @@ _cairo_cache_fini (cairo_cache_t *cache) cairo_cache_entry_t *entry; /* We have to manually remove all entries from the cache ourselves - * rather than relying on _cairo_hash_table_destroy to do that + * rather than relying on _cairo_hash_table_destroy() to do that * since otherwise the cache->entry_destroy callback would not get * called on each entry. */ @@ -92,7 +92,7 @@ _cairo_cache_fini (cairo_cache_t *cache) /** * _cairo_cache_create: - * @keys_equal: a function to return TRUE if two keys are equal + * @keys_equal: a function to return %TRUE if two keys are equal * @entry_destroy: destroy notifier for cache entries * @max_size: the maximum size for this cache * @@ -108,7 +108,7 @@ _cairo_cache_fini (cairo_cache_t *cache) * * The units for max_size can be chosen by the caller, but should be * consistent with the units of the size field of cache entries. When - * adding an entry with _cairo_cache_insert if the total size of + * adding an entry with _cairo_cache_insert() if the total size of * entries in the cache would exceed max_size then entries will be * removed at random until the new entry would fit or the cache is * empty. Then the new entry is inserted. @@ -152,7 +152,7 @@ _cairo_cache_create (cairo_cache_keys_equal_func_t keys_equal, * * Immediately destroys the given cache, freeing all resources * associated with it. As part of this process, the entry_destroy() - * function, (as passed to _cairo_cache_create), will be called for + * function, (as passed to _cairo_cache_create()), will be called for * each entry in the cache. **/ void @@ -169,7 +169,7 @@ _cairo_cache_destroy (cairo_cache_t *cache) * added) * * Disable the automatic ejection of entries from the cache. Future - * calls to _cairo_cache_insert will add new entries to the cache + * calls to _cairo_cache_insert() will add new entries to the cache * regardless of how large the cache grows. See * _cairo_cache_release(). **/ @@ -186,10 +186,10 @@ _cairo_cache_preserve (cairo_cache_t *cache) * * Cancel the effects of _cairo_cache_preserve(). That is, allow the * cache to resume ejecting entries when it is larger than max_size as - * passed to cairo_cache_create. If the cache is already larger than + * passed to cairo_cache_create(). If the cache is already larger than * max_size, no entries will be immediately removed, but the cache * will be brought down to size at the time of the next call to - * _cairo_cache_insert. + * _cairo_cache_insert(). **/ void _cairo_cache_release (cairo_cache_t *cache) @@ -205,11 +205,11 @@ _cairo_cache_release (cairo_cache_t *cache) * * Performs a lookup in @cache looking for an entry which has a key * that matches @key, (as determined by the keys_equal() function - * passed to _cairo_cache_create). + * passed to _cairo_cache_create()). * - * Return value: TRUE if there is an entry in the cache that matches - * @key, (which will now be in *entry_return). FALSE otherwise, (in - * which case *entry_return will be NULL). + * Return value: %TRUE if there is an entry in the cache that matches + * @key, (which will now be in *entry_return). %FALSE otherwise, (in + * which case *entry_return will be %NULL). **/ cairo_private cairo_bool_t _cairo_cache_lookup (cairo_cache_t *cache, @@ -291,7 +291,7 @@ _cairo_cache_insert (cairo_cache_t *cache, * * Remove an entry from the cache which has a key that matches @key, * if any (as determined by the keys_equal() function passed to - * _cairo_cache_create). + * _cairo_cache_create()). **/ cairo_private void _cairo_cache_remove (cairo_cache_t *cache,