Commit fefba953 authored by Nick Mathewson's avatar Nick Mathewson 🤹
Browse files

r11629@catbus: nickm | 2007-02-02 15:06:17 -0500 

 Removing the last DOCDOC comment hurt so much that I had to use Doxygen to identify undocumented macros and comments, and add 150 more DOCDOCs to point out where they were.  Oops.  Hey, kids!  Fixing some of these could be your first Tor patch!


svn:r9477
parent e521c96c

src/common/compat.c

+14 −1
Original line number Diff line number Diff line
@@ -107,17 +107,20 @@ const char compat_c_id[] = 
#include "strlcat.c"

#endif



/* used by inet_addr, not defined on solaris anywhere!? */

#ifndef INADDR_NONE

/* This is used by inet_addr, but apparently Solaris doesn't define it

 * anyplace. */

#define INADDR_NONE ((unsigned long) -1)

#endif



#ifdef HAVE_SYS_MMAN_H

/** DOCDOC */

typedef struct tor_mmap_impl_t {

  tor_mmap_t base;

  size_t mapping_size; /**< Size of the actual mapping. (This is this file

                        * size, rounded up to the nearest page.) */

} tor_mmap_impl_t;

/** DOCDOC */

tor_mmap_t *

tor_mmap_file(const char *filename)

{
@@ -165,6 +168,7 @@ tor_mmap_file(const char *filename) 


  return &(res->base);

}

/** DOCDOC */

void

tor_munmap_file(tor_mmap_t *handle)

{
@@ -174,6 +178,7 @@ tor_munmap_file(tor_mmap_t *handle) 
  tor_free(h);

}

#elif defined(MS_WINDOWS)

/** DOCDOC */

typedef struct win_mmap_t {

  tor_mmap_t base;

  HANDLE file_handle;
@@ -966,6 +971,7 @@ typedef struct tor_pthread_data_t { 
  void (*func)(void *);

  void *data;

} tor_pthread_data_t;

/** DOCDOC */

static void *

tor_pthread_helper_fn(void *_data)

{
@@ -1092,6 +1098,8 @@ tor_gettimeofday(struct timeval *timeval) 
}



#if defined(TOR_IS_MULTITHREADED) && !defined(MS_WINDOWS)

/** Defined iff we need to add locks when defining fake versions of reentrant

 * versions of time-related functions. */

#define TIME_FNS_NEED_LOCKS

#endif
@@ -1206,6 +1214,7 @@ tor_get_thread_id(void) 
struct tor_mutex_t {

  pthread_mutex_t mutex;

};

/** DOCDOC */

tor_mutex_t *

tor_mutex_new(void)

{
@@ -1213,18 +1222,21 @@ tor_mutex_new(void) 
  pthread_mutex_init(&mutex->mutex, NULL);

  return mutex;

}

/** DOCDOC */

void

tor_mutex_acquire(tor_mutex_t *m)

{

  tor_assert(m);

  pthread_mutex_lock(&m->mutex);

}

/** DOCDOC */

void

tor_mutex_release(tor_mutex_t *m)

{

  tor_assert(m);

  pthread_mutex_unlock(&m->mutex);

}

/** DOCDOC */

void

tor_mutex_free(tor_mutex_t *m)

{
@@ -1232,6 +1244,7 @@ tor_mutex_free(tor_mutex_t *m) 
  pthread_mutex_destroy(&m->mutex);

  tor_free(m);

}

/** DOCDOC */

unsigned long

tor_get_thread_id(void)

{

src/common/container.c

+1 −2
Original line number Diff line number Diff line
@@ -28,8 +28,7 @@ const char container_c_id[] = 


#include "ht.h"



/* All newly allocated smartlists have this capacity.

 */

/** All newly allocated smartlists have this capacity. */

#define SMARTLIST_DEFAULT_CAPACITY 32



/** Allocate and return an empty smartlist.

src/common/container.h

+6 −1
Original line number Diff line number Diff line
@@ -11,7 +11,12 @@ 
#include "compat.h"

#include "util.h"



/** A resizeable list of pointers, with associated helpful functionality. */

/** A resizeable list of pointers, with associated helpful functionality.

 *

 * The members of this struct are exposed only so that macros and inlines can

 * use them; all access to smartlist internals should go throuch the functions

 * and macros defined here.

 **/

typedef struct smartlist_t {

  /** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements

   * before it needs to be resized.  Only the first <b>num_used</b> (\<=

src/common/crypto.c

+1 −1
Original line number Diff line number Diff line
@@ -550,7 +550,7 @@ crypto_pk_read_public_key_from_string(crypto_pk_env_t *env, const char *src, 
  return 0;

}



/* Write the private key from 'env' into the file named by 'fname',

/** Write the private key from 'env' into the file named by 'fname',

 * PEM-encoded.  Return 0 on success, -1 on failure.

 */

int

src/common/crypto.h

+2 −0
Original line number Diff line number Diff line
@@ -160,12 +160,14 @@ void *smartlist_choose(const struct smartlist_t *sl); 


int base64_encode(char *dest, size_t destlen, const char *src, size_t srclen);

int base64_decode(char *dest, size_t destlen, const char *src, size_t srclen);

/** Characters that can appear (case-insensitively) in a base-32 encoding. */

#define BASE32_CHARS "abcdefghijklmnopqrstuvwxyz234567"

void base32_encode(char *dest, size_t destlen, const char *src, size_t srclen);



int digest_to_base64(char *d64, const char *digest);

int digest_from_base64(char *digest, const char *d64);



/** DOCDOC */

#define S2K_SPECIFIER_LEN 9

void secret_to_key(char *key_out, size_t key_out_len, const char *secret,

                   size_t secret_len, const char *s2k_specifier);