Ignore:
Timestamp:
Jan 1, 2010, 10:13:27 PM (12 years ago)
Author:
charles
Message:

(trunk libT) improved API documentation / commenting for doxygen

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/libtransmission/ptrarray.h

    r9671 r9845  
    4040extern const tr_ptrArray TR_PTR_ARRAY_INIT;
    4141
    42 void          tr_ptrArrayDestruct( tr_ptrArray*, PtrArrayForeachFunc func );
     42/** @brief Destructor to free a tr_ptrArray's internal memory */
     43void tr_ptrArrayDestruct( tr_ptrArray*, PtrArrayForeachFunc func );
    4344
    44 void          tr_ptrArrayForeach( tr_ptrArray         * array,
    45                                   PtrArrayForeachFunc   func );
     45/** @brief Iterate through each item in a tr_ptrArray */
     46void tr_ptrArrayForeach( tr_ptrArray         * array,
     47                         PtrArrayForeachFunc   func );
    4648
     49/** @brief Return the nth item in a tr_ptrArray
     50    @return the nth item in a tr_ptrArray */
    4751void*         tr_ptrArrayNth( tr_ptrArray   * array,
    4852                              int             nth );
    4953
    50 void*         tr_ptrArrayBack( tr_ptrArray  * array );
     54/** @brief Remove the last item from the array and return it
     55    @return the pointer that's been removed from the array
     56    @see tr_ptrArrayBack() */
     57void* tr_ptrArrayPop( tr_ptrArray * array );
    5158
    52 void**        tr_ptrArrayPeek( tr_ptrArray  * array,
    53                                int          * size );
     59/** @brief Return the last item in a tr_ptrArray
     60    @return the last item in a tr_ptrArray, or NULL if the array is empty
     61    @see tr_ptrArrayPop() */
     62static inline void* tr_ptrArrayBack( tr_ptrArray * array )
     63{
     64    return array->n_items > 0 ? tr_ptrArrayNth( array, array->n_items - 1 )
     65                              : NULL;
     66}
    5467
    55 static TR_INLINE void  tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; }
    5668
    57 int           tr_ptrArrayInsert( tr_ptrArray * array,
    58                                  void        * insertMe,
    59                                  int           pos );
     69/** @brief Peek at the array pointer and its size, for easy iteration */
     70void** tr_ptrArrayPeek( tr_ptrArray * array, int * size );
    6071
    61 static TR_INLINE int tr_ptrArrayAppend( tr_ptrArray * array, void * appendMe )
     72static inline void  tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; }
     73
     74/** @brief Insert a pointer into the array at the specified position
     75    @return the index of the stored pointer */
     76int tr_ptrArrayInsert( tr_ptrArray * array, void * insertMe, int pos );
     77
     78/** @brief Append a pointer into the array */
     79static inline int tr_ptrArrayAppend( tr_ptrArray * array, void * appendMe )
    6280{
    6381    return tr_ptrArrayInsert( array, appendMe, -1 );
    6482}
    6583
    66 void*         tr_ptrArrayPop( tr_ptrArray    * array );
    67 
    68 static TR_INLINE void** tr_ptrArrayBase( const tr_ptrArray * a )
     84static inline void** tr_ptrArrayBase( const tr_ptrArray * a )
    6985{
    7086    return a->items;
    7187}
    7288
    73 static TR_INLINE int tr_ptrArraySize( const tr_ptrArray *  a )
     89/** @brief Return the number of items in the array
     90    @return the number of items in the array */
     91static inline int tr_ptrArraySize( const tr_ptrArray *  a )
    7492{
    7593    return a->n_items;
    7694}
    7795
    78 static TR_INLINE tr_bool tr_ptrArrayEmpty( const tr_ptrArray * a )
     96/** @brief Return True if the array has no pointers
     97    @return True if the array has no pointers */
     98static inline tr_bool tr_ptrArrayEmpty( const tr_ptrArray * a )
    7999{
    80100    return tr_ptrArraySize(a) == 0;
    81101}
    82102
    83 int           tr_ptrArrayInsertSorted( tr_ptrArray * array,
    84                                        void        * value,
    85                                        int compare(const void*, const void*) );
     103/** @brief Insert a pointer into the array at the position determined by the sort function
     104    @return the index of the stored pointer */
     105int tr_ptrArrayInsertSorted( tr_ptrArray * array,
     106                             void        * value,
     107                             int compare(const void*, const void*) );
    86108
    87 void*         tr_ptrArrayRemoveSorted( tr_ptrArray * array,
    88                                        void        * value,
    89                                        int compare(const void*, const void*) );
     109/** @brief Remove a pointer from an array sorted by the specified sort function
     110    @return the matching pointer, or NULL if no match was found */
     111void* tr_ptrArrayRemoveSorted( tr_ptrArray * array,
     112                               void        * value,
     113                               int compare(const void*, const void*) );
    90114
    91 void*         tr_ptrArrayFindSorted( tr_ptrArray * array,
    92                                      const void  * key,
    93                                      int compare(const void*, const void*) );
     115/** @brief Find a pointer from an array sorted by the specified sort function
     116    @return the matching pointer, or NULL if no match was found */
     117void* tr_ptrArrayFindSorted( tr_ptrArray * array,
     118                             const void  * key,
     119                             int compare(const void*, const void*) );
    94120
    95121/* @} */
Note: See TracChangeset for help on using the changeset viewer.