From aa907f2d51d9409635e5d1438b67efa6857a4c69 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 7 Oct 2009 11:10:42 +0000 Subject: [PATCH] improving documentation --- src/include/gnunet_container_lib.h | 7 ++-- src/include/gnunet_disk_lib.h | 6 ++-- src/util/common_logging.c | 2 +- src/util/configuration.c | 55 +++++++++++++++--------------- src/util/connection.c | 3 +- src/util/container_bloomfilter.c | 1 + src/util/container_meta_data.c | 21 +++++++++--- src/util/container_slist.c | 2 +- src/util/disk.c | 8 ++--- src/util/network.c | 16 +++++---- 10 files changed, 71 insertions(+), 50 deletions(-) diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h index e27a58f13..ec190fdc6 100644 --- a/src/include/gnunet_container_lib.h +++ b/src/include/gnunet_container_lib.h @@ -372,6 +372,7 @@ enum GNUNET_CONTAINER_MetaDataSerializationOptions * Serialize meta-data to target. * * @param md metadata to serialize + * @param target where to write the serialized metadata * @param size maximum number of bytes available * @param opt is it ok to just write SOME of the * meta-data to match the size constraint, @@ -388,9 +389,11 @@ ssize_t GNUNET_CONTAINER_meta_data_serialize (const struct GNUNET_CONTAINER_MetaDataSerializationOptions opt); + /** - * Compute size of the meta-data in - * serialized form. + * Estimate (!) the size of the meta-data in + * serialized form. The estimate MAY be higher + * than what is strictly needed. * * @param md metadata to inspect * @param opt is it ok to just write SOME of the diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h index 38b5df9c6..69f7fb825 100644 --- a/src/include/gnunet_disk_lib.h +++ b/src/include/gnunet_disk_lib.h @@ -548,8 +548,8 @@ GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh, off_t lockStart, /** * Unlock a part of a file * @param fh file handle - * @param lockStart absolute position from where to unlock - * @param lockEnd absolute position until where to unlock + * @param unlockStart absolute position from where to unlock + * @param unlockEnd absolute position until where to unlock * @return GNUNET_OK on success, GNUNET_SYSERR on error */ int @@ -582,7 +582,7 @@ int GNUNET_DISK_file_change_owner (const char *filename, const char *user); * * @param cfg configuration to use * @param serviceName name of the service asking - * @param varargs is NULL-terminated list of + * @param ... is NULL-terminated list of * path components to append to the * private directory name. * @return the constructed filename diff --git a/src/util/common_logging.c b/src/util/common_logging.c index ea3ab4f78..0ee4edbe2 100644 --- a/src/util/common_logging.c +++ b/src/util/common_logging.c @@ -254,7 +254,7 @@ output_message (enum GNUNET_ErrorType kind, /** * Flush an existing bulk report to the output. * - * @param datastr our current timestamp + * @param datestr our current timestamp */ static void flush_bulk (const char *datestr) diff --git a/src/util/configuration.c b/src/util/configuration.c index 569c4adcf..2541a79f4 100644 --- a/src/util/configuration.c +++ b/src/util/configuration.c @@ -278,7 +278,7 @@ GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg) * @return GNUNET_OK on success, GNUNET_SYSERR on error */ int -GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *data, +GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg, const char *filename) { struct ConfigSection *sec; @@ -299,7 +299,7 @@ GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *data, } GNUNET_free (fn); error = 0; - sec = data->sections; + sec = cfg->sections; while (sec != NULL) { if (0 > fprintf (fp, "[%s]\n", sec->name)) @@ -344,10 +344,10 @@ GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *data, GNUNET_assert (0 == fclose (fp)); if (error != 0) { - data->dirty = GNUNET_SYSERR; /* last write failed */ + cfg->dirty = GNUNET_SYSERR; /* last write failed */ return GNUNET_SYSERR; } - data->dirty = GNUNET_NO; /* last write succeeded */ + cfg->dirty = GNUNET_NO; /* last write succeeded */ return GNUNET_OK; } @@ -381,12 +381,13 @@ void GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg /** - * FIXME. + * Copy a configuration value to the given target configuration. + * Overwrites existing entries. * * @param cls the destination configuration (struct GNUNET_CONFIGURATION_Handle*) - * @param section FIXME - * @param option FIXME - * @param value FIXME + * @param section section for the value + * @param option option name of the value + * @param value value to copy */ static void copy_entry (void *cls, @@ -402,7 +403,7 @@ copy_entry (void *cls, /** * Duplicate an existing configuration object. * - * @param c configuration to duplicate + * @param cfg configuration to duplicate * @return duplicate configuration */ struct GNUNET_CONFIGURATION_Handle * @@ -419,16 +420,16 @@ GNUNET_CONFIGURATION_dup (const struct GNUNET_CONFIGURATION_Handle *cfg) /** * FIXME. * - * @param data FIXME + * @param cfg FIXME * @param section FIXME * @return matching entry, NULL if not found */ static struct ConfigSection * -findSection (const struct GNUNET_CONFIGURATION_Handle *data, const char *section) +findSection (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section) { struct ConfigSection *pos; - pos = data->sections; + pos = cfg->sections; while ((pos != NULL) && (0 != strcasecmp (section, pos->name))) pos = pos->next; return pos; @@ -438,19 +439,19 @@ findSection (const struct GNUNET_CONFIGURATION_Handle *data, const char *section /** * FIXME. * - * @param data FIXME + * @param cfg FIXME * @param section FIXME * @param key FIXME * @return matching entry, NULL if not found */ static struct ConfigEntry * -findEntry (const struct GNUNET_CONFIGURATION_Handle *data, +findEntry (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, const char *key) { struct ConfigSection *sec; struct ConfigEntry *pos; - sec = findSection (data, section); + sec = findSection (cfg, section); if (sec == NULL) return NULL; pos = sec->entries; @@ -470,27 +471,27 @@ findEntry (const struct GNUNET_CONFIGURATION_Handle *data, */ void GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle - *data, + *cfg, const char *section, const char *option, const char *value) { struct ConfigSection *sec; struct ConfigEntry *e; - e = findEntry (data, section, option); + e = findEntry (cfg, section, option); if (e != NULL) { GNUNET_free_non_null (e->val); e->val = GNUNET_strdup (value); return; } - sec = findSection (data, section); + sec = findSection (cfg, section); if (sec == NULL) { sec = GNUNET_malloc (sizeof (struct ConfigSection)); sec->name = GNUNET_strdup (section); - sec->next = data->sections; - data->sections = sec; + sec->next = cfg->sections; + cfg->sections = sec; } e = GNUNET_malloc (sizeof (struct ConfigEntry)); e->key = GNUNET_strdup (option); @@ -671,7 +672,7 @@ GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg, * "FOO" is set to "DIRECTORY". * * @param cfg configuration to use for path expansion - * @param old string to $-expand (will be freed!) + * @param orig string to $-expand (will be freed!) * @return $-expanded string */ char * @@ -733,19 +734,19 @@ GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle *cf */ int GNUNET_CONFIGURATION_get_value_filename (const struct GNUNET_CONFIGURATION_Handle - *data, const char *section, + *cfg, const char *section, const char *option, char **value) { int ret; char *tmp; tmp = NULL; - ret = GNUNET_CONFIGURATION_get_value_string (data, section, option, &tmp); + ret = GNUNET_CONFIGURATION_get_value_string (cfg, section, option, &tmp); if (ret == GNUNET_SYSERR) return ret; if (tmp != NULL) { - tmp = GNUNET_CONFIGURATION_expand_dollar (data, tmp); + tmp = GNUNET_CONFIGURATION_expand_dollar (cfg, tmp); *value = GNUNET_STRINGS_filename_expand (tmp); GNUNET_free (tmp); if (*value == NULL) @@ -1054,7 +1055,7 @@ GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle */ int GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg, - const char *cfgfn) + const char *filename) { char *baseconfig; char *ipath; @@ -1068,8 +1069,8 @@ GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg, GNUNET_free (ipath); if ((GNUNET_OK != GNUNET_CONFIGURATION_parse (cfg, baseconfig)) || - (!((cfgfn == NULL) || - (GNUNET_OK == GNUNET_CONFIGURATION_parse (cfg, cfgfn))))) + (!((filename == NULL) || + (GNUNET_OK == GNUNET_CONFIGURATION_parse (cfg, filename))))) { GNUNET_free (baseconfig); return GNUNET_SYSERR; diff --git a/src/util/connection.c b/src/util/connection.c index fa367faf9..1e2f1fca8 100644 --- a/src/util/connection.c +++ b/src/util/connection.c @@ -692,7 +692,7 @@ connect_success_continuation (struct GNUNET_CONNECTION_Handle *h) * Scheduler let us know that we're either ready to write on the * socket OR connect timed out. Do the right thing. * - * @param ap the address we were probing + * @param cls the "struct AddressProbe*" with the address that we are probing * @param tc success or failure info about the connect attempt. */ static void @@ -1188,7 +1188,6 @@ receive_again (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc) * receive call per socket at any given point in time (so do not * call receive again until the receiver callback has been invoked). * - * @param sched scheduler to use * @param sock socket handle * @param max maximum number of bytes to read * @param timeout maximum amount of time to wait (use -1 for "forever") diff --git a/src/util/container_bloomfilter.c b/src/util/container_bloomfilter.c index 39baed6c7..5e69fe8ab 100644 --- a/src/util/container_bloomfilter.c +++ b/src/util/container_bloomfilter.c @@ -520,6 +520,7 @@ GNUNET_CONTAINER_bloomfilter_init (const char *data, * Copy the raw data of this bloomfilter into * the given data array. * + * @param bf bloomfilter to take the raw data from * @param data where to write the data * @param size the size of the given data array * @return GNUNET_SYSERR if the data array is not big enough diff --git a/src/util/container_meta_data.c b/src/util/container_meta_data.c index 4cb4ea148..bbe6dad3b 100644 --- a/src/util/container_meta_data.c +++ b/src/util/container_meta_data.c @@ -247,6 +247,7 @@ GNUNET_CONTAINER_meta_data_get_first_by_types (const struct /** * Get a thumbnail from the meta-data (if present). * + * @param md metadata to get the thumbnail from * @param thumb will be set to the thumbnail data. Must be * freed by the caller! * @return number of bytes in thumbnail, 0 if not available @@ -333,6 +334,7 @@ GNUNET_CONTAINER_meta_data_extract_from_file (struct GNUNET_CONTAINER_MetaData return ret; } + static unsigned int tryCompression (char *data, unsigned int oldSize) { @@ -434,7 +436,9 @@ struct MetaDataHeader /** * Serialize meta-data to target. * - * @param size maximum number of bytes available + * @param md metadata to serialize + * @param target where to write the serialized metadata + * @param max maximum number of bytes available in target * @param part is it ok to just write SOME of the * meta-data to match the size constraint, * possibly discarding some data? @@ -532,13 +536,19 @@ GNUNET_CONTAINER_meta_data_serialize (const struct GNUNET_CONTAINER_MetaData * Estimate (!) the size of the meta-data in * serialized form. The estimate MAY be higher * than what is strictly needed. + * + * @param md metadata to inspect + * @param opt is it ok to just write SOME of the + * meta-data to match the size constraint, + * possibly discarding some data? + * @return number of bytes needed for serialization, -1 on error */ ssize_t GNUNET_CONTAINER_meta_data_get_serialized_size (const struct GNUNET_CONTAINER_MetaData *md, enum GNUNET_CONTAINER_MetaDataSerializationOptions - part) + opt) { struct MetaDataHeader *hdr; size_t size; @@ -567,7 +577,7 @@ GNUNET_CONTAINER_meta_data_get_serialized_size (const struct memcpy (&((char *) hdr)[pos], md->items[i].data, len); pos += len; } - if ((part & GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS) == 0) + if ((opt & GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS) == 0) { pos = tryCompression ((char *) &hdr[1], @@ -583,9 +593,12 @@ GNUNET_CONTAINER_meta_data_get_serialized_size (const struct return size; } + /** * Deserialize meta-data. Initializes md. - * @param size number of bytes available + * + * @param input buffer with the serialized metadata + * @param size number of bytes available in input * @return MD on success, NULL on error (i.e. * bad format) */ diff --git a/src/util/container_slist.c b/src/util/container_slist.c index 1a03fdca3..3d96e26e2 100644 --- a/src/util/container_slist.c +++ b/src/util/container_slist.c @@ -215,7 +215,7 @@ GNUNET_CONTAINER_slist_clear (struct GNUNET_CONTAINER_SList *l) * * @param l list * @param buf payload buffer to find - * @param lenght of the payload + * @param len length of the payload (number of bytes in buf) */ int GNUNET_CONTAINER_slist_contains (const struct GNUNET_CONTAINER_SList *l, diff --git a/src/util/disk.c b/src/util/disk.c index 42d5862a7..fcbb8c0a7 100644 --- a/src/util/disk.c +++ b/src/util/disk.c @@ -536,20 +536,20 @@ GNUNET_DISK_directory_create (const char *dir) * Create the directory structure for storing * a file. * - * @param dir name of a file in the directory + * @param filename name of a file in the directory * @returns GNUNET_OK on success, * GNUNET_SYSERR on failure, * GNUNET_NO if the directory * exists but is not writeable for us */ int -GNUNET_DISK_directory_create_for_file (const char *dir) +GNUNET_DISK_directory_create_for_file (const char *filename) { char *rdir; int len; int ret; - rdir = GNUNET_STRINGS_filename_expand (dir); + rdir = GNUNET_STRINGS_filename_expand (filename); if (rdir == NULL) return GNUNET_SYSERR; len = strlen (rdir); @@ -1367,7 +1367,7 @@ GNUNET_DISK_file_close (struct GNUNET_DISK_FileHandle *h) * * @param cfg configuration to use (determines HOME) * @param serviceName name of the service - * @param varargs is NULL-terminated list of + * @param ... is NULL-terminated list of * path components to append to the * private directory name. * @return the constructed filename diff --git a/src/util/network.c b/src/util/network.c index c10317258..91d4066b2 100644 --- a/src/util/network.c +++ b/src/util/network.c @@ -384,22 +384,26 @@ GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc, /** * Make a non-inheritable to child processes - * @param socket + * + * @param h the socket to make non-inheritable * @return GNUNET_OK on success, GNUNET_SYSERR otherwise * @warning Not implemented on Windows */ int GNUNET_NETWORK_socket_set_inheritable (const struct GNUNET_NETWORK_Handle - *desc) + *h) { #ifdef MINGW errno = ENOSYS; return GNUNET_SYSERR; #else - return fcntl (desc->fd, F_SETFD, - fcntl (desc->fd, - F_GETFD) | FD_CLOEXEC) == - 0 ? GNUNET_OK : GNUNET_SYSERR; + int i; + + i = fcntl (h->fd, F_GETFD); + if (i == (i | FD_CLOEXEC)) + return GNUNET_OK; + return (fcntl (h->fd, F_SETFD, i | FD_CLOEXEC) == 0) + ? GNUNET_OK : GNUNET_SYSERR; #endif } -- 2.25.1