r13851: More doc improvements.

(This used to be commit 936d26ae64b93ef8f8b2fbc632b1c2fd60840405)

11 files changed, 134 insertions, 25 deletions

diff --git a/source4/lib/util/capability.c b/source4/lib/util/capability.c
index 0062bb5cd6..09af293087 100644
--- a/source4/lib/util/capability.c
+++ b/source4/lib/util/capability.c
@@ -103,9 +103,9 @@ static BOOL set_inherited_process_capability( uint32_t cap_flag, BOOL enable )
 }
 #endif
 
-/****************************************************************************
+/**
  Gain the oplock capability from the kernel if possible.
-****************************************************************************/
+**/
 
 _PUBLIC_ void oplock_set_capability(BOOL this_process, BOOL inherit)
 {
diff --git a/source4/lib/util/data_blob.c b/source4/lib/util/data_blob.c
index c1513a1d78..ac6589aa50 100644
--- a/source4/lib/util/data_blob.c
+++ b/source4/lib/util/data_blob.c
@@ -178,6 +178,10 @@ _PUBLIC_ DATA_BLOB data_blob_string_const(const char *str)
 	return blob;
 }
 
+/**
+ * Create a new data blob from const data 
+ */
+
 _PUBLIC_ DATA_BLOB data_blob_const(const void *p, size_t length)
 {
 	DATA_BLOB blob;
diff --git a/source4/lib/util/debug.c b/source4/lib/util/debug.c
index 1c5bb25753..e4f13ea28e 100644
--- a/source4/lib/util/debug.c
+++ b/source4/lib/util/debug.c
@@ -29,10 +29,11 @@
  * @brief Debug logging
  **/
 
-/* this global variable determines what messages are printed */
+/** 
+ * this global variable determines what messages are printed 
+ */
 _PUBLIC_ int DEBUGLEVEL;
 
-
 /* the registered mutex handlers */
 static struct {
 	const char *name;
@@ -64,7 +65,7 @@ static void log_timestring(int level, const char *location, const char *func)
 	free(s);
 }
 
-/*
+/**
   the backend for debug messages. Note that the DEBUG() macro has already
   ensured that the log level has been met before this is called
 */
@@ -74,9 +75,12 @@ _PUBLIC_ void do_debug_header(int level, const char *location, const char *func)
 	log_task_id();
 }
 
-/*
+/**
   the backend for debug messages. Note that the DEBUG() macro has already
   ensured that the log level has been met before this is called
+
+  @note You should never have to call this function directly. Call the DEBUG()
+  macro instead.
 */
 _PUBLIC_ void do_debug(const char *format, ...) _PRINTF_ATTRIBUTE(1,2)
 {
diff --git a/source4/lib/util/debug.h b/source4/lib/util/debug.h
index 4cd5759119..10d7d0697c 100644
--- a/source4/lib/util/debug.h
+++ b/source4/lib/util/debug.h
@@ -18,6 +18,11 @@
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
 
+/**
+ * @file
+ * @brief Debugging macros
+ */
+
 /* If we have these macros, we can add additional info to the header. */
 
 #ifdef HAVE_FUNCTION_MACRO
@@ -54,10 +59,21 @@ extern int DEBUGLEVEL;
 		do_debug body; \
 	} \
 } while (0)
+/** 
+ * Write to the debug log.
+ */
 #define DEBUG(level, body) _DEBUG(level, body, True)
+/**
+ * Add data to an existing debug log entry.
+ */
 #define DEBUGADD(level, body) _DEBUG(level, body, False)
-#define DEBUGC(class, level, body) DEBUG(level, body)
-#define DEBUGADDC(class, level, body) DEBUGADD(level, body)
+
+/**
+ * Obtain indentation string for the debug log. 
+ *
+ * Level specified by n.
+ */
 #define DEBUGTAB(n) do_debug_tab(n)
 
+/** Possible destinations for the debug log */
 enum debug_logtype {DEBUG_STDOUT = 0, DEBUG_FILE = 1, DEBUG_STDERR = 2};
diff --git a/source4/lib/util/genrand.c b/source4/lib/util/genrand.c
index f2b038f161..5bdf1f7e08 100644
--- a/source4/lib/util/genrand.c
+++ b/source4/lib/util/genrand.c
@@ -46,6 +46,9 @@ _PUBLIC_ void set_rand_reseed_callback(void (*fn)(int *))
 	set_need_random_reseed();
 }
 
+/**
+ * Tell the random number generator it needs to reseed.
+ */
 _PUBLIC_ void set_need_random_reseed(void)
 {
 	done_reseed = False;
@@ -299,6 +302,13 @@ _PUBLIC_ char *generate_random_str_list(TALLOC_CTX *mem_ctx, size_t len, const c
 	return retstr;
 }
 
+/**
+ * Generate a random text string consisting of the specified length.
+ * The returned string will be allocated.
+ *
+ * Characters used are: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+_-#.,
+ */
+
 _PUBLIC_ char *generate_random_str(TALLOC_CTX *mem_ctx, size_t len)
 {
 	char *retstr;
diff --git a/source4/lib/util/mutex.h b/source4/lib/util/mutex.h
index 018c134bcb..bdc7bc7e7a 100644
--- a/source4/lib/util/mutex.h
+++ b/source4/lib/util/mutex.h
@@ -21,6 +21,11 @@
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
 
+/** 
+ * @file
+ * @brief Mutex operations
+ */
+
 struct mutex_ops;
 
 /* To add a new read/write lock, add it to enum rwlock_id
diff --git a/source4/lib/util/unix_privs.c b/source4/lib/util/unix_privs.c
index 13b0aa203c..c94cf619a3 100644
--- a/source4/lib/util/unix_privs.c
+++ b/source4/lib/util/unix_privs.c
@@ -59,6 +59,12 @@ static int privileges_destructor(void *ptr)
 	return 0;
 }
 
+/**
+ * Obtain root privileges for the current process.
+ *
+ * The privileges can be dropped by talloc_free()-ing the 
+ * token returned by this function
+ */
 void *root_privileges(void)
 {
 	struct saved_state *s;
diff --git a/source4/lib/util/util.c b/source4/lib/util/util.c
index 81084878b5..ec25a9cbc7 100644
--- a/source4/lib/util/util.c
+++ b/source4/lib/util/util.c
@@ -93,6 +93,12 @@ _PUBLIC_ BOOL directory_exist(const char *dname)
 	return ret;
 }
 
+/**
+ * Try to create the specified directory if it didn't exist.
+ *
+ * @retval True if the directory already existed and has the right permissions 
+ * or was successfully created.
+ */
 _PUBLIC_ BOOL directory_create_or_exist(const char *dname, uid_t uid, 
 			       mode_t dir_perms)
 {
@@ -486,6 +492,11 @@ static void print_asc(int level, const uint8_t *buf,int len)
 		DEBUGADD(level,("%c", isprint(buf[i])?buf[i]:'.'));
 }
 
+/**
+ * Write dump of binary data to the log file.
+ *
+ * The data is only written if the log level is at least level.
+ */
 _PUBLIC_ void dump_data(int level, const uint8_t *buf,int len)
 {
 	int i=0;
@@ -688,6 +699,12 @@ static char *modules_path(TALLOC_CTX* mem_ctx, const char *name)
 	return talloc_asprintf(mem_ctx, "%s/%s", dyn_MODULESDIR, name);
 }
 
+/**
+ * Load the initialization functions from DSO files for a specific subsystem.
+ *
+ * Will return an array of function pointers to initialization functions
+ */
+
 _PUBLIC_ init_module_fn *load_samba_modules(TALLOC_CTX *mem_ctx, const char *subsystem)
 {
 	char *path = modules_path(mem_ctx, subsystem);
@@ -700,6 +717,12 @@ _PUBLIC_ init_module_fn *load_samba_modules(TALLOC_CTX *mem_ctx, const char *sub
 	return ret;
 }
 
+/**
+ * Write a password to the log file.
+ *
+ * @note Only actually does something if DEBUG_PASSWORD was defined during 
+ * compile-time.
+ */
 _PUBLIC_ void dump_data_pw(const char *msg, const uint8_t * data, size_t len)
 {
 #ifdef DEBUG_PASSWORD
diff --git a/source4/lib/util/util.h b/source4/lib/util/util.h
index 272cc13f4e..1dfd942dd3 100644
--- a/source4/lib/util/util.h
+++ b/source4/lib/util/util.h
@@ -100,8 +100,20 @@ struct substitute_context;
 #define SAFE_FREE(x) do { if ((x) != NULL) {free(discard_const_p(void *, (x))); (x)=NULL;} } while(0)
 #endif
 
+/** 
+ * Type-safe version of malloc. Allocated one copy of the 
+ * specified data type.
+ */
 #define malloc_p(type) (type *)malloc(sizeof(type))
+
+/**
+ * Allocate an array of elements of one data type. Does type-checking.
+ */
 #define malloc_array_p(type, count) (type *)realloc_array(NULL, sizeof(type), count)
+
+/** 
+ * Resize an array of elements of one data type. Does type-checking.
+ */
 #define realloc_p(p, type, count) (type *)realloc_array(p, sizeof(type), count)
 
 #if defined(VALGRIND)
@@ -127,6 +139,8 @@ struct substitute_context;
   makes the return type safe.
 */
 #define discard_const(ptr) ((void *)((intptr_t)(ptr)))
+
+/** Type-safe version of discard_const */
 #define discard_const_p(type, ptr) ((type *)discard_const(ptr))
 
 #endif /* _SAMBA_UTIL_H_ */
diff --git a/source4/lib/util/util_str.c b/source4/lib/util/util_str.c
index ef6abd6e83..4bb3ea1b54 100644
--- a/source4/lib/util/util_str.c
+++ b/source4/lib/util/util_str.c
@@ -436,6 +436,9 @@ _PUBLIC_ size_t strhex_to_str(char *p, size_t len, const char *strhex)
 	return num_chars;
 }
 
+/** 
+ * Parse a hex string and return a data blob. 
+ */
 _PUBLIC_ DATA_BLOB strhex_to_data_blob(const char *strhex) 
 {
 	DATA_BLOB ret_blob = data_blob(NULL, strlen(strhex)/2+1);
@@ -643,6 +646,9 @@ _PUBLIC_ char *strchr_m(const char *s, char c)
 	return NULL;
 }
 
+/**
+ * Multibyte-character version of strrchr
+ */
 _PUBLIC_ char *strrchr_m(const char *s, char c)
 {
 	char *ret = NULL;
@@ -665,7 +671,7 @@ _PUBLIC_ char *strrchr_m(const char *s, char c)
 	return ret;
 }
 
-/*
+/**
   return True if any (multi-byte) character is lower case
 */
 _PUBLIC_ BOOL strhaslower(const char *string)
@@ -688,7 +694,7 @@ _PUBLIC_ BOOL strhaslower(const char *string)
 	return False;
 } 
 
-/*
+/**
   return True if any (multi-byte) character is upper case
 */
 _PUBLIC_ BOOL strhasupper(const char *string)
@@ -1016,6 +1022,12 @@ _PUBLIC_ const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s)
 	return ret;
 }
 
+/**
+ * Add a string to an array of strings.
+ *
+ * num should be a pointer to an integer that holds the current 
+ * number of elements in strings. It will be updated by this function.
+ */
 _PUBLIC_ BOOL add_string_to_array(TALLOC_CTX *mem_ctx,
 			 const char *str, const char ***strings, int *num)
 {
@@ -1137,6 +1149,13 @@ _PUBLIC_ BOOL set_boolean(const char *boolean_string, BOOL *boolean)
 	return False;
 }
 
+/**
+ * Parse a string containing a boolean value.
+ *
+ * val will be set to the read value.
+ *
+ * @retval True if a boolean value was parsed, False otherwise.
+ */
 _PUBLIC_ BOOL conv_str_bool(const char * str, BOOL * val)
 {
 	char *	end = NULL;
@@ -1192,6 +1211,13 @@ _PUBLIC_ BOOL conv_str_size(const char * str, uint64_t * val)
 	return True;
 }
 
+/**
+ * Parse a uint64_t value from a string
+ *
+ * val will be set to the value read.
+ *
+ * @retval True if parsing was successful, False otherwise
+ */
 _PUBLIC_ BOOL conv_str_u64(const char * str, uint64_t * val)
 {
 	char *		    end = NULL;
diff --git a/source4/lib/util/xfile.c b/source4/lib/util/xfile.c
index 43f0f85f52..97bab2ef9a 100644
--- a/source4/lib/util/xfile.c
+++ b/source4/lib/util/xfile.c
@@ -51,7 +51,7 @@ XFILE *x_stderr = &_x_stderr;
 #define X_FLAG_ERROR 2
 #define X_FLAG_EINVAL 3
 
-/* simulate setvbuf() */
+/** simulate setvbuf() */
 int x_setvbuf(XFILE *f, char *buf, int mode, size_t size)
 {
 	x_fflush(f);
@@ -93,7 +93,7 @@ static int x_allocate_buffer(XFILE *f)
 }
 
 
-/* this looks more like open() than fopen(), but that is quite deliberate.
+/** this looks more like open() than fopen(), but that is quite deliberate.
    I want programmers to *think* about O_EXCL, O_CREAT etc not just
    get them magically added 
 */
@@ -126,7 +126,7 @@ XFILE *x_fopen(const char *fname, int flags, mode_t mode)
 	return ret;
 }
 
-/* simulate fclose() */
+/** simulate fclose() */
 int x_fclose(XFILE *f)
 {
 	int ret;
@@ -150,7 +150,7 @@ int x_fclose(XFILE *f)
 	return ret;
 }
 
-/* simulate fwrite() */
+/** simulate fwrite() */
 size_t x_fwrite(const void *p, size_t size, size_t nmemb, XFILE *f)
 {
 	ssize_t ret;
@@ -195,7 +195,7 @@ size_t x_fwrite(const void *p, size_t size, size_t nmemb, XFILE *f)
 	return total/size;
 }
 
-/* thank goodness for asprintf() */
+/** thank goodness for asprintf() */
  int x_vfprintf(XFILE *f, const char *format, va_list ap)
 {
 	char *p;
@@ -228,7 +228,7 @@ int x_fileno(XFILE *f)
 	return f->fd;
 }
 
-/* simulate fflush() */
+/** simulate fflush() */
 int x_fflush(XFILE *f)
 {
 	int ret;
@@ -255,33 +255,33 @@ int x_fflush(XFILE *f)
 	return 0;
 }
 
-/* simulate setbuffer() */
+/** simulate setbuffer() */
 void x_setbuffer(XFILE *f, char *buf, size_t size)
 {
 	x_setvbuf(f, buf, buf?X_IOFBF:X_IONBF, size);
 }
 
-/* simulate setbuf() */
+/** simulate setbuf() */
 void x_setbuf(XFILE *f, char *buf)
 {
 	x_setvbuf(f, buf, buf?X_IOFBF:X_IONBF, XBUFSIZE);
 }
 
-/* simulate setlinebuf() */
+/** simulate setlinebuf() */
 void x_setlinebuf(XFILE *f)
 {
 	x_setvbuf(f, NULL, X_IOLBF, 0);
 }
 
 
-/* simulate feof() */
+/** simulate feof() */
 int x_feof(XFILE *f)
 {
 	if (f->flags & X_FLAG_EOF) return 1;
 	return 0;
 }
 
-/* simulate ferror() */
+/** simulate ferror() */
 int x_ferror(XFILE *f)
 {
 	if (f->flags & X_FLAG_ERROR) return 1;
@@ -303,7 +303,7 @@ static void x_fillbuf(XFILE *f)
 	f->next = f->buf;
 }
 
-/* simulate fgetc() */
+/** simulate fgetc() */
 int x_fgetc(XFILE *f)
 {
 	int ret;
@@ -323,7 +323,7 @@ int x_fgetc(XFILE *f)
 	return ret;
 }
 
-/* simulate fread */
+/** simulate fread */
 size_t x_fread(void *p, size_t size, size_t nmemb, XFILE *f)
 {
 	size_t total = 0;
@@ -336,7 +336,7 @@ size_t x_fread(void *p, size_t size, size_t nmemb, XFILE *f)
 	return total/size;
 }
 
-/* simulate fgets() */
+/** simulate fgets() */
 char *x_fgets(char *s, int size, XFILE *stream) 
 {
 	char *s0 = s;
@@ -355,7 +355,8 @@ char *x_fgets(char *s, int size, XFILE *stream)
 	return s0;
 }
 
-/* trivial seek, works only for SEEK_SET and SEEK_END if SEEK_CUR is
+/** 
+ * trivial seek, works only for SEEK_SET and SEEK_END if SEEK_CUR is
  * set then an error is returned */
 off_t x_tseek(XFILE *f, off_t offset, int whence)
 {