Changeset 9891


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

(trunk libT) more documentation and doxygen markup

Location:
trunk/libtransmission
Files:
8 edited

Legend:

Unmodified
Added
Removed
  • trunk/libtransmission/crypto.h

    r9868 r9891  
    8989
    9090
    91 /** Returns a random number in the range of [0...n) */
     91/** @brief Returns a random number in the range of [0...n) */
    9292int            tr_cryptoRandInt( int n );
    9393
    94 /** Returns a vaguely random number in the range of [0...n).
    95     This is faster -- BUT WEAKER -- than tr_cryptoRandInt()
    96     and should only be used when tr_cryptoRandInt() is too
    97     slow, and NEVER in sensitive cases */
     94/**
     95 * @brief Returns a vaguely random number in the range of [0...n).
     96 *
     97 * This is faster, BUT WEAKER, than tr_cryptoRandInt() and never
     98 * be used in sensitive cases.
     99 * @see tr_cryptoRandInt()
     100 */
    98101int            tr_cryptoWeakRandInt( int n );
    99102
    100 /** Fills a buffer with random bytes */
     103/** @brief Fills a buffer with random bytes */
    101104void           tr_cryptoRandBuf( void * buf, size_t len );
    102105
  • trunk/libtransmission/ggets.h

    r8561 r9891  
    4040#endif
    4141
    42 /** @ingroup utils */
     42/**
     43 * @brief read a line from a file and place it in a newly-allocated string
     44 * @ingroup utils
     45 */
    4346int fggets( char* *ln, FILE * f );
    4447
  • trunk/libtransmission/list.c

    r9868 r9891  
    178178}
    179179
    180 void
     180static void
    181181__tr_list_splice( struct __tr_list * prev,
    182182                  struct __tr_list * next)
  • 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
  • trunk/libtransmission/ptrarray.h

    r9868 r9891  
    2626
    2727/**
    28  * A simple pointer array that resizes itself dynamically.
     28 * @brief simple pointer array that resizes itself dynamically.
    2929 */
    3030typedef struct tr_ptrArray
  • trunk/libtransmission/session.h

    r9868 r9891  
    4242struct tr_fdInfo;
    4343
     44/** @brief handle to an active libtransmission session */
    4445struct tr_session
    4546{
  • trunk/libtransmission/transmission.h

    r9890 r9891  
    16361636
    16371637/**
    1638  * The current status of a torrent.
     1638 * @brief Describes a torrent's status
    16391639 * @see tr_torrentStat()
    16401640 */
  • trunk/libtransmission/utils.h

    r9890 r9891  
    189189FILE*          tr_getLog( void );
    190190
    191 tr_bool        tr_deepLoggingIsActive( void );
     191/** @brief return true if deep logging has been enabled by the user; false otherwise */
     192tr_bool tr_deepLoggingIsActive( void );
    192193
    193194void           tr_deepLog( const char * file,
     
    197198                           ... ) TR_GNUC_PRINTF( 4, 5 ) TR_GNUC_NONNULL(1,4);
    198199
    199 char*          tr_getLogTimeStr( char * buf,
    200                                  int    buflen ) TR_GNUC_NONNULL(1);
     200/** @brief set the buffer with the current time formatted for deep logging. */
     201char* tr_getLogTimeStr( char * buf, int buflen ) TR_GNUC_NONNULL(1);
    201202
    202203
     
    467468
    468469
    469 /* truncate a double value at a given number of decimal places.
    470    this can be used to prevent a printf() call from rounding up:
    471    call with the decimal_places argument equal to the number of
    472    decimal places in the printf()'s precision:
    473 
    474    - printf("%.2f%%",           99.999    ) ==> "100.00%"
    475 
    476    - printf("%.2f%%", tr_truncd(99.999, 2)) ==>  "99.99%"
    477                ^                        ^
    478                |   These should match   |
    479                +------------------------+
    480 */
     470/**
     471 * @brief truncate a double value at a given number of decimal places.
     472 *
     473 * this can be used to prevent a printf() call from rounding up:
     474 * call with the decimal_places argument equal to the number of
     475 * decimal places in the printf()'s precision:
     476 *
     477 * - printf("%.2f%%",           99.999    ) ==> "100.00%"
     478 *
     479 * - printf("%.2f%%", tr_truncd(99.999, 2)) ==>  "99.99%"
     480 *             ^                        ^
     481 *             |   These should match   |
     482 *             +------------------------+
     483 */
    481484double tr_truncd( double x, int decimal_places );
    482485
     
    493496
    494497
    495 /** on success, return 0.  on failure, return -1 and set errno */
     498/**
     499 * @brief move a file
     500 * @return 0 on success; otherwise, return -1 and set errno
     501 */
    496502int tr_moveFile( const char * oldpath, const char * newpath,
    497503                 tr_bool * renamed ) TR_GNUC_NONNULL(1,2);
    498504
     505/** @brief convenience function to remove an item from an array */
    499506static inline void tr_removeElementFromArray( void   * array,
    500                                                  int      index_to_remove,
    501                                                  size_t   sizeof_element,
    502                                                  size_t   nmemb )
     507                                              int      index_to_remove,
     508                                              size_t   sizeof_element,
     509                                              size_t   nmemb )
    503510{
    504511    char * a = (char*) array;
Note: See TracChangeset for help on using the changeset viewer.