(trunk) No code changes here... filling in some of the blanks in the "peers" and "utils" doxygen groups' documentation.

libtransmission/announcer.c

@@ -353,10 +353,7 @@ trackerFree( void * vtracker )
 
 struct tr_torrent_tiers;
 
-/**
+/** @brief A group of trackers in a single tier, as per the multitracker spec */
- * A group of trackers in a single tier,
- * as per the multitracker spec
- */
 typedef struct
 {
     tr_ptrArray trackers; /* tr_tracker_item */
@@ -469,8 +466,9 @@ tierAddTracker( tr_announcer * announcer,
 ****
 ***/
 
-/*
+/**
- * per-torrent info.
+ * @brief Opaque, per-torrent data structure for tracker announce information
+ *
  * this opaque data structure can be found in tr_torrent.tiers
  */
 typedef struct tr_torrent_tiers

libtransmission/announcer.h

@@ -36,6 +36,7 @@ typedef enum
 }
 TrackerEventType;
 
+/** @brief Notification object to tell listeners about announce or scrape occurences */
 typedef struct
 {
     /* what type of event this is */

libtransmission/bencode.c

@@ -1176,6 +1176,7 @@ tr_bencFree( tr_benc * val )
 ****
 ***/
 
+/** @brief Implementation helper class for tr_bencToBuffer(TR_FMT_JSON) */
 struct ParentState
 {
     int    bencType;
@@ -1183,6 +1184,7 @@ struct ParentState
     int    childCount;
 };
 
+/** @brief Implementation helper class for tr_bencToBuffer(TR_FMT_JSON) */
 struct jsonWalk
 {
     tr_bool doIndent;

libtransmission/bencode.h

@@ -198,12 +198,24 @@ tr_bool   tr_bencDictFindRaw( tr_benc *, const char * key,
 ****
 ***/
 
+/** @brief Get an int64_t from a variant object
+    @return TRUE if successful, or FALSE if the variant could not be represented as an int64_t  */
 tr_bool   tr_bencGetInt( const tr_benc * val, int64_t * setme );
+
+/** @brief Get an string from a variant object
+    @return TRUE if successful, or FALSE if the variant could not be represented as a string  */
 tr_bool   tr_bencGetStr( const tr_benc * val, const char ** setme );
+
+/** @brief Get a boolean from a variant object
+    @return TRUE if successful, or FALSE if the variant could not be represented as a boolean  */
 tr_bool   tr_bencGetBool( const tr_benc * val, tr_bool * setme );
+
+/** @brief Get a floating-point number from a variant object
+    @return TRUE if successful, or FALSE if the variant could not be represented as a floating-point number  */
 tr_bool   tr_bencGetReal( const tr_benc * val, double * setme );
 
 static inline tr_bool tr_bencIsType  ( const tr_benc * b, int type ) { return ( b != NULL ) && ( b->type == type ); }
+
 static inline tr_bool tr_bencIsInt   ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_INT ); }
 static inline tr_bool tr_bencIsDict  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_DICT ); }
 static inline tr_bool tr_bencIsList  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_LIST ); }
@@ -211,16 +223,13 @@ static inline tr_bool tr_bencIsString( const tr_benc * b ) { return tr_bencIsTyp
 static inline tr_bool tr_bencIsBool  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_BOOL ); }
 static inline tr_bool tr_bencIsReal  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_REAL ); }
 
-/**
+/** @brief Private function that's exposed here only for unit tests */
-***  Treat these as private -- they're only made public here
-***  so that the unit tests can find them
-**/
-
 int tr_bencParseInt( const uint8_t *  buf,
                      const uint8_t *  bufend,
                      const uint8_t ** setme_end,
                      int64_t *        setme_val );
 
+/** @brief Private function that's exposed here only for unit tests */
 int tr_bencParseStr( const uint8_t *  buf,
                      const uint8_t *  bufend,
                      const uint8_t ** setme_end,

libtransmission/bitfield.h

@@ -20,6 +20,7 @@
 #include "transmission.h"
 #include "utils.h" /* tr_new0 */
 
+/** @brief Implementation of the BitTorrent spec's Bitfield array of bits */
 typedef struct tr_bitfield
 {
     uint8_t *  bits;

libtransmission/bitset.h

@@ -22,7 +22,7 @@
 #include "transmission.h"
 #include "bitfield.h"
 
-/** This like a tr_bitfield, but supports haveAll and haveNone */
+/** @brief like a tr_bitfield, but supports haveAll and haveNone */
 typedef struct tr_bitset
 {
     tr_bool haveAll;

libtransmission/clients.h

@@ -18,6 +18,7 @@
 #define TR_CLIENTS_H
 
 /**
+ * @brief parse a peer-id into a human-readable client name and version number
  * @ingroup utils
  */
 void tr_clientForId( char * buf, size_t buflen, const void * peer_id );

libtransmission/crypto.c

@@ -86,6 +86,7 @@ static const uint8_t dh_P[PRIME_LEN] =
 
 static const uint8_t dh_G[] = { 2 };
 
+/** @brief Holds state information for encrypted peer communications */
 struct tr_crypto
 {
     RC4_KEY         dec_key;

libtransmission/crypto.h

@@ -28,36 +28,25 @@
 struct evbuffer;
 
 /**
- * @addtogroup utils Utilities
+*** @addtogroup peers
- * @{
+*** @{
- */
+**/
 
 typedef struct tr_crypto tr_crypto;
 
-/**
+/** @brief create a new tr_crypto object */
-***
+tr_crypto*  tr_cryptoNew( const uint8_t * torrentHash, int isIncoming );
-**/
-
-tr_crypto*     tr_cryptoNew( const uint8_t * torrentHash,
-                             int             isIncoming );
 
+/** @brief destroy an existing tr_crypto object */
 void           tr_cryptoFree( tr_crypto * crypto );
 
-/**
-***
-**/
 
-void           tr_cryptoSetTorrentHash( tr_crypto *     crypto,
+void tr_cryptoSetTorrentHash( tr_crypto * crypto, const uint8_t * torrentHash );
-                                        const uint8_t * torrentHash );
 
 const uint8_t* tr_cryptoGetTorrentHash( const tr_crypto * crypto );
 
 int            tr_cryptoHasTorrentHash( const tr_crypto * crypto );
 
-/**
-***
-**/
-
 const uint8_t* tr_cryptoComputeSecret( tr_crypto *     crypto,
                                        const uint8_t * peerPublicKey );
 
@@ -71,10 +60,6 @@ void           tr_cryptoDecrypt( tr_crypto *  crypto,
                                  const void * buf_in,
                                  void *       buf_out );
 
-/**
-***
-**/
-
 void           tr_cryptoEncryptInit( tr_crypto * crypto );
 
 void           tr_cryptoEncrypt( tr_crypto *  crypto,
@@ -82,17 +67,26 @@ void           tr_cryptoEncrypt( tr_crypto *  crypto,
                                  const void * buf_in,
                                  void *       buf_out );
 
-void           tr_sha1( uint8_t *    setme,
+/* @} */
-                        const void * content1,
-                        int          content1_len,
-                        ... ) TR_GNUC_NULL_TERMINATED;
-
-
-/** @brief Returns a random number in the range of [0...n) */
-int            tr_cryptoRandInt( int n );
 
 /**
- * @brief Returns a vaguely random number in the range of [0...n).
+*** @addtogroup utils Utilities
+*** @{
+**/
+
+
+/** @brief generate a SHA1 hash from one or more chunks of memory */
+void tr_sha1( uint8_t    * setme,
+              const void * content1,
+              int          content1_len,
+              ... ) TR_GNUC_NULL_TERMINATED;
+
+
+/** @brief returns a random number in the range of [0...n) */
+int tr_cryptoRandInt( int n );
+
+/**
+ * @brief returns a pseudorandom number in the range of [0...n)
  *
  * This is faster, BUT WEAKER, than tr_cryptoRandInt() and never
  * be used in sensitive cases.
@@ -100,12 +94,14 @@ int            tr_cryptoRandInt( int n );
  */
 int            tr_cryptoWeakRandInt( int n );
 
-/** @brief Fills a buffer with random bytes */
+/** @brief fill a buffer with random bytes */
-void           tr_cryptoRandBuf( void * buf, size_t len );
+void  tr_cryptoRandBuf( void * buf, size_t len );
 
-char*          tr_ssha1( const void * plaintext );
+/** @brief generate a SSHA password from its plaintext source */
+char*  tr_ssha1( const void * plaintext );
 
-tr_bool        tr_ssha1_matches( const char * source, const char * pass );
+/** @brief Validate a test password against the a ssha1 password */
+tr_bool tr_ssha1_matches( const char * ssha1, const char * pass );
 
 /* @} */
 

libtransmission/peer-mgr.c

@@ -160,6 +160,7 @@ struct weighted_piece
     int16_t requestCount;
 };
 
+/** @brief Opaque, per-torrent data structure for peer connection information */
 typedef struct tr_torrent_peers
 {
     tr_ptrArray                outgoingHandshakes; /* tr_handshake */

libtransmission/platform.c

@@ -78,6 +78,7 @@ tr_areThreadsEqual( tr_thread_id a,
 #endif
 }
 
+/** @brief portability wrapper around OS-dependent threads */
 struct tr_thread
 {
     void            ( * func )( void * );
@@ -142,6 +143,7 @@ tr_threadNew( void   ( *func )(void *),
 ****  LOCKS
 ***/
 
+/** @brief portability wrapper around OS-dependent thread mutexes */
 struct tr_lock
 {
     int                 depth;
@@ -378,8 +380,7 @@ migrateFiles( const tr_session * session )
 }
 
 void
-tr_setConfigDir( tr_session * session,
+tr_setConfigDir( tr_session * session, const char * configDir )
-                 const char * configDir )
 {
     char * path;
 

libtransmission/platform.h

@@ -34,28 +34,38 @@
 
 #define MAX_STACK_ARRAY_SIZE 7168
 
+/**
+ * @addtogroup tr_session Session
+ * @{
+ */
+
+/**
+ * @brief invoked by tr_sessionInit() to set up the locations of the resume, torrent, and clutch directories.
+ * @see tr_getResumeDir()
+ * @see tr_getTorrentDir()
+ * @see tr_getClutchDir()
+ */
+void tr_setConfigDir( tr_session * session, const char * configDir );
+
+/** @brief return the directory where .resume files are stored */
+const char * tr_getResumeDir( const tr_session * );
+
+/** @brief return the directory where .torrent files are stored */
+const char * tr_getTorrentDir( const tr_session * );
+
+/** @brief return the directory where Clutch's web ui files are kept */
+const char * tr_getClutchDir( const tr_session * );
+
+/** @} */
+
+
 /**
  * @addtogroup utils Utilities
  * @{
  */
 
-typedef struct tr_lock   tr_lock;
 typedef struct tr_thread tr_thread;
 
-void                tr_setConfigDir( tr_session * session,
-                                     const char * configDir );
-
-const char *        tr_getResumeDir( const tr_session * );
-
-const char *        tr_getTorrentDir( const tr_session * );
-
-const char *        tr_getClutchDir( const tr_session * );
-
-
-/***
-****
-***/
-
 /** @brief Instantiate a new process thread */
 tr_thread* tr_threadNew( void ( *func )(void *), void * arg );
 
@@ -67,6 +77,8 @@ int tr_amInThread( const tr_thread * );
 ****
 ***/
 
+typedef struct tr_lock tr_lock;
+
 /** @brief Create a new thread mutex object */
 tr_lock * tr_lockNew( void );
 
@@ -83,16 +95,9 @@ void tr_lockUnlock( tr_lock * );
 int tr_lockHave( const tr_lock * );
 
 #ifdef WIN32
-void *              mmap( void *ptr,
+void * mmap( void *ptr, long  size, long  prot, long  type, long  handle, long  arg );
-                          long  size,
-                          long  prot,
-                          long  type,
-                          long  handle,
-                          long  arg );
-
-long                munmap( void *ptr,
-                            long  size );
 
+long munmap( void *ptr, long  size );
 #endif
 
 /* @} */

libtransmission/session.c

@@ -576,8 +576,10 @@ onNowTimer( int foo UNUSED, short bar UNUSED, void * vsession )
     if( usec > max ) usec = max;
     if( usec < min ) usec = min;
     tr_timerAdd( session->nowTimer, 0, usec );
+
+    /* update libtransmission's epoch time */
     tr_timeUpdate( tv.tv_sec );
-    /* fprintf( stderr, "time %zu sec, %zu microsec\n", (size_t)tr_time(), (size_t)tv.tv_usec );  */
+    /* fprintf( stderr, "time %zu sec, %zu microsec\n", (size_t)tr_time(), (size_t)tv.tv_usec ); */
 }
 
 static void loadBlocklists( tr_session * session );

libtransmission/stats.c

@@ -23,6 +23,7 @@
 
 static struct tr_session_stats STATS_INIT = { 0.0f, 0, 0, 0, 0, 0 };
 
+/** @brief Opaque, per-session data structure for bandwidth use statistics */
 struct tr_stats_handle
 {
     tr_session_stats    single;

libtransmission/torrent.h

@@ -134,6 +134,7 @@ void             tr_torrentSetVerifyState( tr_torrent      * tor,
 
 struct tr_incomplete_metadata;
 
+/** @brief Torrent object */
 struct tr_torrent
 {
     tr_session *             session;

libtransmission/transmission.h

@@ -340,7 +340,7 @@ void tr_sessionSetDownloadDir( tr_session * session, const char * downloadDir );
 const char * tr_sessionGetDownloadDir( const tr_session * session );
 
 /**
- * @brief Set the per-session incomplete download folder.
+ * @brief set the per-session incomplete download folder.
  *
  * When you add a new torrent and the session's incomplete directory is enabled,
  * the new torrent will start downloading into that directory, and then be moved
@@ -360,10 +360,13 @@ const char * tr_sessionGetDownloadDir( const tr_session * session );
  */
 void tr_sessionSetIncompleteDir( tr_session * session, const char * dir );
 
+/** @brief get the per-session incomplete download folder */
 const char* tr_sessionGetIncompleteDir( const tr_session * session );
 
+/** @brief enable or disable use of the incomplete download folder */
 void tr_sessionSetIncompleteDirEnabled( tr_session * session, tr_bool );
 
+/** @brief get whether or not the incomplete download folder is enabled */
 tr_bool tr_sessionIsIncompleteDirEnabled( const tr_session * session );
 
 
@@ -378,6 +381,7 @@ tr_bool tr_sessionIsIncompleteDirEnabled( const tr_session * session );
  */
 void tr_sessionSetIncompleteFileNamingEnabled( tr_session * session, tr_bool );
 
+/** @brief return whether or filenames will have ".part" at the end until they're complete */
 tr_bool tr_sessionIsIncompleteFileNamingEnabled( const tr_session * session );
 
 /**
@@ -538,6 +542,7 @@ void          tr_sessionSetProxyPassword( tr_session * session,
 ***
 **/
 
+/** @brief Used by tr_sessionGetStats() and tr_sessionGetCumulativeStats() to give bandwidth statistics */ 
 typedef struct tr_session_stats
 {
     float       ratio;        /* TR_RATIO_INF, TR_RATIO_NA, or total up/down */
@@ -549,23 +554,21 @@ typedef struct tr_session_stats
 }
 tr_session_stats;
 
-/* stats from the current session. */
+/** @brief Get bandwidth use statistics about the current session */
-void               tr_sessionGetStats( const tr_session * session,
+void tr_sessionGetStats( const tr_session * session, tr_session_stats * setme );
-                                       tr_session_stats * setme );
 
-/* stats from the current and past sessions. */
+/** @brief Get cumulative bandwidth use statistics for the current and past sessions */
-void               tr_sessionGetCumulativeStats( const tr_session * session,
+void tr_sessionGetCumulativeStats( const tr_session * session, tr_session_stats * setme );
-                                                 tr_session_stats * setme );
 
-void               tr_sessionClearStats( tr_session * session );
+void tr_sessionClearStats( tr_session * session );
 
 /**
- * Set whether or not torrents are allowed to do peer exchanges.
+ * @brief Set whether or not torrents are allowed to do peer exchanges.
+ *
  * PEX is always disabled in private torrents regardless of this.
  * In public torrents, PEX is enabled by default.
  */
-void               tr_sessionSetPexEnabled( tr_session  * session,
+void tr_sessionSetPexEnabled( tr_session  * session, tr_bool isEnabled );
-                                            tr_bool       isEnabled );
 
 tr_bool            tr_sessionIsPexEnabled( const tr_session * session );
 
@@ -1639,10 +1642,7 @@ typedef enum
 }
 tr_stat_errtype;
 
-/**
+/** @brief Used by tr_torrentStat() to tell clients about a torrent's state and statistics */
- * @brief Describes a torrent's status
- * @see tr_torrentStat()
- */
 typedef struct tr_stat
 {
     /** The torrent's unique Id.

libtransmission/utils.h

@@ -519,6 +519,7 @@ static inline void tr_removeElementFromArray( void   * array,
 ****
 ***/
 
+/** @brief Private libtransmission variable that's visible only for inlining in tr_time() */
 extern time_t transmission_now;
 
 /**