Ignore:
Timestamp:
Jan 6, 2010, 12:18:33 AM (12 years ago)
Author:
charles
Message:

(trunk libT) more documentation and doxygen markup

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/libtransmission/list.h

    r9868 r9891  
    1818#define TR_LIST_H
    1919
     20/**
     21 * @addtogroup utils Utilities
     22 * @{
     23 */
     24
    2025#include "transmission.h" /* inline */
    2126
     27/** @brief simple list structure similar to glib's GList */
    2228typedef struct tr_list
    2329{
     
    3137typedef void ( *TrListForeachFunc )( void * );
    3238
     39/**
     40 * @brief return the number of items in the list
     41 * @return the number of items in the list
     42 */
    3343int      tr_list_size( const tr_list * list );
    3444
    35 void     tr_list_free( tr_list **        list,
    36                        TrListForeachFunc data_free_func );
     45/**
     46 * @brief free the specified list and set its pointer to NULL
     47 * @param list pointer to the list to be freed
     48 * @param func optional function to invoke on each item in the list
     49 */
     50void     tr_list_free( tr_list ** list, TrListForeachFunc data_free_func );
    3751
    38 void     tr_list_append( tr_list ** list,
    39                          void *     data );
     52/**
     53 * @brief append an item to the specified list
     54 * @param list pointer to the list
     55 * @param item the item to append
     56 */
     57void tr_list_append( tr_list ** list, void * data );
    4058
    41 void     tr_list_prepend( tr_list ** list,
    42                           void *     data );
     59/**
     60 * @brief prepend an item to the specified list
     61 * @param list pointer to the list
     62 * @param item the item to prepend
     63 */
     64void tr_list_prepend( tr_list ** list, void * data );
    4365
    44 void*    tr_list_pop_front( tr_list ** list );
     66/**
     67 * @brief remove the next item in the list
     68 * @return the next item in the list, or NULL if the list is empty
     69 * @param list pointer to the list
     70 */
     71void* tr_list_pop_front( tr_list ** list );
    4572
    46 void*    tr_list_remove_data( tr_list **   list,
    47                               const void * data );
     73/**
     74 * @brief remove the list's node that contains the specified data pointer
     75 * @param list pointer to the list
     76 * @param data data to remove
     77 * @return the removed data pointer, or NULL if no match was found
     78 */
     79void* tr_list_remove_data( tr_list ** list, const void * data );
    4880
     81/**
     82 * @brief remove the list's node that compares equal to "b" when compared with "compare_func"
     83 * @param list pointer to the list
     84 * @param b the comparison key
     85 * @param compare_func the comparison function.  The arguments passed to it will be the list's pointers and the comparison key "b"
     86 * @return the removed data pointer, or NULL if no match was found
     87 */
    4988void*    tr_list_remove( tr_list **        list,
    5089                         const void *      b,
    5190                         TrListCompareFunc compare_func );
    5291
     92/**
     93 * @brief find the list node whose data that compares equal to "b" when compared with "compare_func"
     94 * @param list pointer to the list
     95 * @param b the comparison key
     96 * @param compare_func the comparison function.  The arguments passed to it will be the list's pointers and the comparison key "b"
     97 * @return the matching list node, or NULL if not match was found
     98 */
    5399tr_list* tr_list_find( tr_list *         list,
    54100                       const void *      b,
     
    56102
    57103
    58 /*
    59  * Double-linked list with easy memory management and fast
    60  * insert/remove operations
    61  */
    62 
     104/** @brief Double-linked list with easy memory management and fast insert/remove operations */
    63105struct __tr_list
    64106{
     
    67109
    68110/**
    69  * Given a __tr_list node that's embedded in a struct, returns a pointer to the struct.
     111 * @brief Given a __tr_list node that's embedded in a struct, returns a pointer to the struct.
    70112 * @param ptr     pointer to the embedded __tr_list
    71113 * @param type    struct type that has contains the __tr_list
     
    78120
    79121
    80 /**
    81  *    __tr_list_init()
    82  *
    83  * Init @head as an empty list.
    84  */
     122/** @brief Init @head as an empty list. */
    85123static inline void
    86124__tr_list_init( struct __tr_list * head )
     
    90128
    91129
    92 /**
    93  *    __tr_list_insert()
    94  *
    95  * Insert @list between @prev and @next.
    96  */
     130/** @brief Insert @list between @prev and @next. */
    97131void
    98132__tr_list_insert( struct __tr_list * list,
     
    100134                  struct __tr_list * next);
    101135
    102 /**
    103  *    __tr_list_splice()
    104  *
    105  * Connect @prev with @next, removing any nodes that were
    106  * in between.
    107  */
    108 void
    109 __tr_list_splice( struct __tr_list * prev,
    110                   struct __tr_list * next);
    111 
    112 /**
    113  *    __tr_list_append()
    114  *
    115  * Append @list to the end of @head.
    116  */
     136/** @brief Append @list to the end of @head. */
    117137static inline void
    118 __tr_list_append( struct __tr_list * head,
    119                   struct __tr_list * list)
     138__tr_list_append( struct __tr_list * head, struct __tr_list * list)
    120139{
    121140    __tr_list_insert( list, head->prev, head );
    122141}
    123142
     143/** @brief Remove @head from the list it is in. */
     144void __tr_list_remove( struct __tr_list * head );
    124145
    125 /**
    126  *    __tr_list_remove()
    127  *
    128  * Remove @head from the list it is in.
    129  */
    130 void
    131 __tr_list_remove( struct __tr_list * head );
     146/** @brief Destroy the list and free all nodes */
     147void __tr_list_destroy( struct __tr_list * head, __tr_list_free_t func );
    132148
    133 /**
    134  *    __tr_list_destroy()
    135  *
    136  * Destroy the list and free all nodes
    137  */
    138 void
    139 __tr_list_destroy( struct __tr_list * head,
    140                    __tr_list_free_t   func);
    141 
     149/* @} */
    142150#endif /* TR_LIST_H */
    143151
Note: See TracChangeset for help on using the changeset viewer.