r9715@catbus: nickm | 2007-01-22 02:51:04 -0500

Document a few undocumented functions and arguments.


svn:r9385
This commit is contained in:
Nick Mathewson 2007-01-22 07:51:06 +00:00
parent d634e5b9af
commit 84790d059f
6 changed files with 62 additions and 21 deletions

View File

@ -940,7 +940,11 @@ consider_hibernation(time_t now)
}
}
/** DOCDOC */
/** Helper function: called when we get a GETINFO request for an
* accounting-related key on the control connection <b>conn</b>. If we can
* answer the request for <b>question</b>, then set *<b>answer</b> to a newly
* allocated string holding the result. Otherwise, set *<b>answer</b> to
* NULL. */
int
getinfo_helper_accounting(control_connection_t *conn,
const char *question, char **answer)

View File

@ -1088,7 +1088,8 @@ ip_address_changed(int at_interface)
dns_servers_relaunch_checks();
}
/* DOCDOC */
/** Forget what we've learned about the correctness of our DNS servers, and
* start learning again. */
void
dns_servers_relaunch_checks(void)
{
@ -2285,7 +2286,9 @@ _tor_dmalloc_free(void *p)
}
#endif
/** DOCDOC */
/** Main entry point for the Tor process. Called from main(). */
/* This function is distinct from main() only so we can link main.c into
* the unittest binary without conflicting with the unittests' main. */
int
tor_main(int argc, char *argv[])
{

View File

@ -916,8 +916,23 @@ typedef struct cached_dir_t {
int refcnt; /**< Reference count for this cached_dir_t. */
} cached_dir_t;
/** Enum used to remember where a signed_descriptor_t is stored and how to
* manage the memory for signed_descriptor_body. */
typedef enum {
SAVED_NOWHERE=0, SAVED_IN_CACHE, SAVED_IN_JOURNAL
/** The descriptor isn't stored on disk at all: the copy in memory is
* canonical; the saved_offset field is meaningless. */
SAVED_NOWHERE=0,
/** The descriptor is stored in the cached_routers file: the
* signed_descriptor_body is meaningless; the signed_descriptor_len and
* saved_offset are used to index into the mmaped cache file. */
SAVED_IN_CACHE,
/** The descriptor is stored in the cached_routers.new file: the
* signed_descriptor_body and saved_offset fields are both set. */
/* FFFF (We could also mmap the file and grow the mmap as needed, or
* lazy-load the descriptor text by using seek and read. We don't, for
* now.)
*/
SAVED_IN_JOURNAL
} saved_location_t;
/** Information need to cache an onion router's descriptor. */

View File

@ -381,7 +381,7 @@ static int can_reach_or_port = 0;
/** Whether we can reach our DirPort from the outside. */
static int can_reach_dir_port = 0;
/** DOCDOC */
/** Forget what we have learned about our reachability status. */
void
router_reset_reachability(void)
{
@ -769,7 +769,8 @@ router_get_my_descriptor(void)
return body;
}
/*DOCDOC*/
/** A list of nicknames that we've warned about including in our family
* declaration verbatim rather than as digests. */
static smartlist_t *warned_nonexistent_family = NULL;
static int router_guess_address_from_dir_headers(uint32_t *guess);
@ -1315,7 +1316,13 @@ is_legal_hexdigest(const char *s)
strspn(s,HEX_CHARACTERS)==HEX_DIGEST_LEN);
}
/** DOCDOC buf must have MAX_VERBOSE_NICKNAME_LEN+1 bytes. */
/** Set <b>buf</b> (which must have MAX_VERBOSE_NICKNAME_LEN+1 bytes) to the
* verbose representation of the identity of <b>router</b>. The format is:
* A dollar sign.
* The upper-case hexadecimal encoding of the SHA1 hash of router's identity.
* A "=" if the router is named; a "~" if it is not.
* The router's nickname.
**/
void
router_get_verbose_nickname(char *buf, routerinfo_t *router)
{

View File

@ -186,7 +186,8 @@ router_should_rebuild_store(void)
}
/** Add the <b>len</b>-type router descriptor in <b>s</b> to the router
* journal. */
* journal; change its saved_locatino to SAVED_IN_JOURNAL and set its
* offset appropriately. */
static int
router_append_to_journal(signed_descriptor_t *desc)
{
@ -1316,7 +1317,9 @@ router_get_by_descriptor_digest(const char *digest)
return digestmap_get(routerlist->desc_digest_map, digest);
}
/* DOCDOC Not always nul-terminated. */
/** Return a pointer to the signed textual representation of a descriptor.
* The returned string is not guaranteed to be NUL-terminated: the string's
* length will be in desc->signed_descriptor_len. */
const char *
signed_descriptor_get_body(signed_descriptor_t *desc)
{
@ -2146,14 +2149,14 @@ router_load_single_router(const char *s, uint8_t purpose, const char **msg)
}
/** Given a string <b>s</b> containing some routerdescs, parse it and put the
* routers into our directory. If <b>from_cache</b> is false, the routers
* are in response to a query to the network: cache them.
* routers into our directory. If saved_location is SAVED_NOWHERE, the routers
* are in response to a query to the network: cache them by adding them to
* the journal.
*
* If <b>requested_fingerprints</b> is provided, it must contain a list of
* uppercased identity fingerprints. Do not update any router whose
* fingerprint is not on the list; after updating a router, remove its
* fingerprint from the list.
* DOCDOC saved_location
*/
void
router_load_routers_from_string(const char *s, saved_location_t saved_location,
@ -3975,9 +3978,9 @@ router_have_minimum_dir_info(void)
return have_min_dir_info;
}
/** DOCDOC
* Must change when authorities change, networkstatuses change, or list of
* routerdescs changes, or number of running routers changes.
/** Called when our internal view of the directory has changed. This can be
* when the authorities change, networkstatuses change, the list of routerdescs
* changes, or number of running routers changes.
*/
static void
router_dir_info_changed(void)
@ -3985,7 +3988,9 @@ router_dir_info_changed(void)
need_to_update_have_min_dir_info = 1;
}
/** DOCDOC */
/** Change the value of have_min_dir_info, setting it true iff we have enough
* network and router information to build circuits. Clear the value of
* need_to_update_have_min_dir_info. */
static void
update_router_have_minimum_dir_info(void)
{
@ -4251,7 +4256,8 @@ getinfo_helper_networkstatus(control_connection_t *conn,
return 0;
}
/*DOCDOC*/
/** Assert that the internal representation of <b>rl</b> is
* self-consistent. */
static void
routerlist_assert_ok(routerlist_t *rl)
{

View File

@ -632,8 +632,13 @@ check_directory_signature(const char *digest,
* descriptors, parses them and stores the result in <b>dest</b>. All routers
* are marked running and valid. Advances *s to a point immediately
* following the last router entry. Ignore any trailing router entries that
* are not complete. Returns 0 on success and -1 on failure.
* DOCDOC saved_location
* are not complete.
*
* If <b>saved_location</b> isn't SAVED_IN_CACHE, make a local copy of each
* descriptor in the signed_descriptor_body field of each routerinfo_t. If it
* isn't SAVED_NOWHERE, remember the offset of each descriptor.
*
* Returns 0 on success and -1 on failure.
*/
int
router_parse_list_from_string(const char **s, smartlist_t *dest,
@ -719,8 +724,9 @@ dump_distinct_digest_count(int severity)
/** Helper function: reads a single router entry from *<b>s</b> ...
* *<b>end</b>. Mallocs a new router and returns it if all goes well, else
* returns NULL.
* DOCDOC cache_copy
* returns NULL. If <b>cache_copy</b> is true, duplicate the contents of
* s through end into the signed_descriptor_body of the resulting
* routerinfo_t.
*/
routerinfo_t *
router_parse_entry_from_string(const char *s, const char *end,