2002-11-23 Havoc Pennington <hp@pobox.com>

* configure.in: pile on more warning flags if using gcc

	* Doxyfile.in (EXTRACT_STATIC): set to NO, so we don't have
	to document static functions

	* configure.in: add summary to end of configure so it
	looks nice and attractive

	* dbus/dbus-hash.c: finish implementation and write unit
	tests and docs

	* configure.in: add --enable-tests to enable unit tests

	* dbus/dbus-test.c: test program to run unit tests
	for all files in dbus/*, initially runs a test for
	dbus-hash.c

	* dbus/dbus-internals.h: file to hold some internal utility stuff

ChangeLog

@@ -1,3 +1,24 @@
+2002-11-23  Havoc Pennington  <hp@pobox.com>
+
+	* configure.in: pile on more warning flags if using gcc
+
+	* Doxyfile.in (EXTRACT_STATIC): set to NO, so we don't have 
+	to document static functions
+
+	* configure.in: add summary to end of configure so it 
+	looks nice and attractive
+
+	* dbus/dbus-hash.c: finish implementation and write unit 
+	tests and docs
+
+	* configure.in: add --enable-tests to enable unit tests
+
+	* dbus/dbus-test.c: test program to run unit tests 
+	for all files in dbus/*, initially runs a test for 
+	dbus-hash.c
+	
+	* dbus/dbus-internals.h: file to hold some internal utility stuff
+
 2002-11-22  Havoc Pennington  <hp@redhat.com>
 
 	* dbus/dbus-hash.c: copy in Tcl hash table, not yet 

Doxyfile.in

@@ -9,7 +9,7 @@ OUTPUT_DIRECTORY       = doc/api
 OUTPUT_LANGUAGE        = English
 EXTRACT_ALL            = NO
 EXTRACT_PRIVATE        = NO
-EXTRACT_STATIC         = YES
+EXTRACT_STATIC         = NO
 HIDE_UNDOC_MEMBERS     = NO
 HIDE_UNDOC_CLASSES     = NO
 BRIEF_MEMBER_DESC      = YES

configure.in

@@ -21,8 +21,17 @@ AC_ISC_POSIX
 AC_HEADER_STDC
 AM_PROG_LIBTOOL
 
-AC_ARG_ENABLE(qt,   [  --disable-qt      disable Qt-friendly client library],enable_qt=no,enable_qt=yes)
+AC_ARG_ENABLE(qt,      [  --disable-qt      disable Qt-friendly client library],enable_qt=no,enable_qt=yes)
-AC_ARG_ENABLE(glib, [  --disable-glib    disable GLib-friendly client library],enable_glib=no,enable_glib=yes)
+AC_ARG_ENABLE(glib,    [  --disable-glib    disable GLib-friendly client library],enable_glib=no,enable_glib=yes)
+AC_ARG_ENABLE(tests,   [  --enable-tests enable unit test code],enable_tests=yes,enable_tests=no)
+AC_ARG_ENABLE(ansi,    [  --enable-ansi enable -ansi -pedantic gcc flags],enable_ansi=yes,enable_ansi=no)
+
+dnl DBUS_BUILD_TESTS controls unit tests built in to .c files 
+dnl and also some stuff in the test/ subdir
+AM_CONDITIONAL(DBUS_BUILD_TESTS, test x$enable_tests = xyes)
+if test x$enable_tests = xyes; then
+    AC_DEFINE(DBUS_BUILD_TESTS,1,[Build test code])
+fi
 
 changequote(,)dnl
 if test "x$GCC" = "xyes"; then
@@ -30,6 +39,53 @@ if test "x$GCC" = "xyes"; then
   *[\ \	]-Wall[\ \	]*) ;;
   *) CFLAGS="$CFLAGS -Wall" ;;
   esac
+
+  case " $CFLAGS " in
+  *[\ \	]-Wchar-subscripts[\ \	]*) ;;
+  *) CFLAGS="$CFLAGS -Wchar-subscripts" ;;
+  esac
+
+  case " $CFLAGS " in
+  *[\ \	]-Wmissing-declarations[\ \	]*) ;;
+  *) CFLAGS="$CFLAGS -Wmissing-declarations" ;;
+  esac
+
+  case " $CFLAGS " in
+  *[\ \	]-Wmissing-prototypes[\ \	]*) ;;
+  *) CFLAGS="$CFLAGS -Wmissing-prototypes" ;;
+  esac
+
+  case " $CFLAGS " in
+  *[\ \	]-Wnested-externs[\ \	]*) ;;
+  *) CFLAGS="$CFLAGS -Wnested-externs" ;;
+  esac
+
+  case " $CFLAGS " in
+  *[\ \	]-Wpointer-arith[\ \	]*) ;;
+  *) CFLAGS="$CFLAGS -Wpointer-arith" ;;
+  esac
+
+  case " $CFLAGS " in
+  *[\ \	]-Wcast-align[\ \	]*) ;;
+  *) CFLAGS="$CFLAGS -Wcast-align" ;;
+  esac
+
+  case " $CFLAGS " in
+  *[\ \	]-Wsign-compare[\ \	]*) ;;
+  *) CFLAGS="$CFLAGS -Wsign-compare" ;;
+  esac
+
+  if test "x$enable_ansi" = "xyes"; then
+    case " $CFLAGS " in
+    *[\ \	]-ansi[\ \	]*) ;;
+    *) CFLAGS="$CFLAGS -ansi" ;;
+    esac
+
+    case " $CFLAGS " in
+    *[\ \	]-pedantic[\ \	]*) ;;
+    *) CFLAGS="$CFLAGS -pedantic" ;;
+    esac
+  fi
 fi
 changequote([,])dnl
 
@@ -65,3 +121,28 @@ test/Makefile
 doc/Makefile
 dbus-1.0.pc
 ])
+
+dnl ==========================================================================
+echo "
+                    D-BUS $VERSION
+                  ==============
+
+	prefix:                 ${prefix}
+	source code location:	${srcdir}
+	compiler:		${CC}
+
+        Building unit tests:    ${enable_tests}
+        Building Qt bindings:   ${enable_qt}
+        Building GLib bindings: ${enable_glib}
+"
+
+if test x$enable_tests = xyes; then
+        echo "NOTE: building with unit tests increases the size of the installed library"
+fi
+if test x$enable_qt = xyes; then
+        echo "NOTE: Qt bindings don't actually exist yet"
+fi
+if test x$enable_glib = xyes; then
+        echo "NOTE: GLib bindings don't actually exist yet"
+fi
+

dbus/Makefile.am

@@ -24,9 +24,24 @@ noinst_LTLIBRARIES=libdbus-convenience.la
 
 libdbus_convenience_la_SOURCES=			\
 	dbus-hash.c				\
-	dbus-hash.h
+	dbus-hash.h				\
+	dbus-internals.c			\
+	dbus-internals.h
 
 libdbus_1_la_LIBADD=  $(DBUS_CLIENT_LIBS) libdbus-convenience.la
 ## don't export symbols that start with "_" (we use this 
 ## convention for internal symbols)
 libdbus_1_la_LDFLAGS= -export-symbols-regex "^[[^_]].*"
+
+if DBUS_BUILD_TESTS
+noinst_PROGRAMS=dbus-test
+
+dbus_test_SOURCES=				\
+	dbus-test.c				\
+	dbus-test.h
+
+dbus_test_LDADD= $(DBUS_CLIENT_LIBS) libdbus-convenience.la libdbus-1.la
+
+## so that "make check" works
+TESTS=dbus-test
+endif

dbus/dbus-hash.h

@@ -24,13 +24,10 @@
 #ifndef DBUS_HASH_H
 #define DBUS_HASH_H
 
-DBUS_BEGIN_DECLS
-
 #include <dbus/dbus-memory.h>
 #include <dbus/dbus-types.h>
 
-typedef struct DBusHashTable DBusHashTable;
+DBUS_BEGIN_DECLS
-typedef struct DBusHashIter  DBusHashIter;
 
 /* The iterator is on the stack, but its real fields are
  * hidden privately.
@@ -38,18 +35,25 @@ typedef struct DBusHashIter  DBusHashIter;
 struct DBusHashIter
 {
   void *dummy1;
-  int   dummy2;
+  void *dummy2;
   void *dummy3;
+  void *dummy4;
+  int   dummy5;
+  int   dummy6;
 };
 
+typedef struct DBusHashTable DBusHashTable;
+typedef struct DBusHashIter  DBusHashIter;
+
 /* Allowing an arbitrary function as with GLib
- * would probably be nicer, but this is internal API so
+ * would be nicer for a public API, but for
- * who cares
+ * an internal API this saves typing, we can add
+ * more whenever we feel like it.
  */
 typedef enum
 {
-  DBUS_HASH_STRING,
+  DBUS_HASH_STRING, /**< Hash keys are strings. */
-  DBUS_HASH_INT
+  DBUS_HASH_INT     /**< Hash keys are integers. */
 } DBusHashType;
 
 DBusHashTable* _dbus_hash_table_new   (DBusHashType     type,
@@ -58,31 +62,37 @@ DBusHashTable* _dbus_hash_table_new   (DBusHashType     type,
 void           _dbus_hash_table_ref   (DBusHashTable   *table);
 void           _dbus_hash_table_unref (DBusHashTable   *table);
 
-/* usage "while (_dbus_hash_table_iterate (table, &iter)) { }" */
+void        _dbus_hash_iter_init (DBusHashTable *table,
-dbus_bool_t _dbus_hash_table_iterate (DBusHashTable *table,
+                                  DBusHashIter  *iter);
-                                      DBusHashIter  *iter);
+dbus_bool_t _dbus_hash_iter_next (DBusHashIter  *iter);
 
-void*       _dbus_hash_iter_get_value      (DBusHashEntry *iter);
+void        _dbus_hash_iter_remove_entry   (DBusHashIter *iter);
-void        _dbus_hash_iter_set_value      (DBusHashEntry *iter,
+void*       _dbus_hash_iter_get_value      (DBusHashIter *iter);
+void        _dbus_hash_iter_set_value      (DBusHashIter *iter,
+                                            void         *value);
+int         _dbus_hash_iter_get_int_key    (DBusHashIter *iter);
+const char* _dbus_hash_iter_get_string_key (DBusHashIter *iter);
+
+dbus_bool_t _dbus_hash_iter_lookup         (DBusHashTable *table,
+                                            void          *key,
+                                            dbus_bool_t    create_if_not_found,
+                                            DBusHashIter  *iter);
+
+void*       _dbus_hash_table_lookup_string (DBusHashTable *table,
+                                            const char    *key);
+void*       _dbus_hash_table_lookup_int    (DBusHashTable *table,
+                                            int            key);
+void        _dbus_hash_table_remove_string (DBusHashTable *table,
+                                            const char    *key);
+void        _dbus_hash_table_remove_int    (DBusHashTable *table,
+                                            int            key);
+dbus_bool_t _dbus_hash_table_insert_string (DBusHashTable *table,
+                                            char          *key,
                                             void          *value);
-int         _dbus_hash_iter_get_int_key    (DBusHashIter  *iter);
+dbus_bool_t _dbus_hash_table_insert_int    (DBusHashTable *table,
-const char* _dbus_hash_iter_get_string_key (DBusHashIter  *iter);
+                                            int            key,
-
+                                            void          *value);
-void* _dbus_hash_table_lookup_string (DBusHashTable *table,
+int         _dbus_hash_table_get_n_entries (DBusHashTable *table);
-                                      const char    *key);
-void* _dbus_hash_table_lookup_int    (DBusHashTable *table,
-                                      int            key);
-void  _dbus_hash_table_remove_string (DBusHashTable *table,
-                                      const char    *key);
-void  _dbus_hash_table_remove_int    (DBusHashTable *table,
-                                      int            key);
-void  _dbus_hash_table_insert_string (DBusHashTable *table,
-                                      const char    *key,
-                                      void          *value);
-void  _dbus_hash_table_insert_int    (DBusHashTable *table,
-                                      int            key,
-                                      void          *value);
-
 
 DBUS_END_DECLS
 

dbus/dbus-macros.h

@@ -50,4 +50,47 @@
 #  endif /* !__cplusplus */
 #endif
 
+/* Normally docs are in .c files, but there isn't a .c file for this. */
+/**
+ * @defgroup DBusMacros Utility macros
+ * @ingroup  DBus
+ * @brief #TRUE, #FALSE, #NULL, and so on
+ *
+ * Utility macros.
+ *
+ * @{
+ */
+
+/**
+ * @def DBUS_BEGIN_DECLS
+ *
+ * Macro used prior to declaring functions in the D-BUS header
+ * files. Expands to "extern "C"" when using a C++ compiler,
+ * and expands to nothing when using a C compiler.
+ */
+/**
+ * @def DBUS_END_DECLS
+ *
+ * Macro used after declaring functions in the D-BUS header
+ * files. Expands to "}" when using a C++ compiler,
+ * and expands to nothing when using a C compiler.
+ */
+/**
+ * @def TRUE
+ *
+ * Expands to "1"
+ */
+/**
+ * @def FALSE
+ *
+ * Expands to "0"
+ */
+/**
+ * @def NULL
+ *
+ * A null pointer, defined appropriately for C or C++.
+ */
+
+/** }@ */
+
 #endif /* DBUS_MACROS_H */

dbus/dbus-memory.c

@@ -25,7 +25,7 @@
 #include <stdlib.h>
 
 /**
- * @defgroup Memory Memory Allocation
+ * @defgroup DBusMemory Memory Allocation
  * @ingroup  DBus
  * @brief dbus_malloc(), dbus_free(), etc.
  *
@@ -45,7 +45,7 @@
  *
  * @param type type name to allocate
  * @param count number of instances in the allocated array
- * @returns the new memory block or NULL on failure
+ * @returns the new memory block or #NULL on failure
  */
 
 /**
@@ -59,7 +59,7 @@
  *
  * @param type type name to allocate
  * @param count number of instances in the allocated array
- * @returns the new memory block or NULL on failure
+ * @returns the new memory block or #NULL on failure
  */
 
 /**
@@ -72,12 +72,12 @@
 
 /**
  * Allocates the given number of bytes, as with standard
- * malloc(). Guaranteed to return NULL if bytes is zero
+ * malloc(). Guaranteed to return #NULL if bytes is zero
- * on all platforms. Returns NULL if the allocation fails.
+ * on all platforms. Returns #NULL if the allocation fails.
  * The memory must be released with dbus_free().
  *
  * @param bytes number of bytes to allocate
- * @return allocated memory, or NULL if the allocation fails.
+ * @return allocated memory, or #NULL if the allocation fails.
  */
 void*
 dbus_malloc (size_t bytes)
@@ -91,11 +91,11 @@ dbus_malloc (size_t bytes)
 /**
  * Allocates the given number of bytes, as with standard malloc(), but
  * all bytes are initialized to zero as with calloc(). Guaranteed to
- * return NULL if bytes is zero on all platforms. Returns NULL if the
+ * return #NULL if bytes is zero on all platforms. Returns #NULL if the
  * allocation fails.  The memory must be released with dbus_free().
  *
  * @param bytes number of bytes to allocate
- * @return allocated memory, or NULL if the allocation fails.
+ * @return allocated memory, or #NULL if the allocation fails.
  */
 void*
 dbus_malloc0 (size_t bytes)
@@ -108,13 +108,13 @@ dbus_malloc0 (size_t bytes)
 
 /**
  * Resizes a block of memory previously allocated by dbus_malloc() or
- * dbus_malloc0(). Guaranteed to free the memory and return NULL if bytes
+ * dbus_malloc0(). Guaranteed to free the memory and return #NULL if bytes
- * is zero on all platforms. Returns NULL if the resize fails.
+ * is zero on all platforms. Returns #NULL if the resize fails.
  * If the resize fails, the memory is not freed.
  *
  * @param memory block to be resized
  * @param bytes new size of the memory block
- * @return allocated memory, or NULL if the resize fails.
+ * @return allocated memory, or #NULL if the resize fails.
  */
 void*
 dbus_realloc (void  *memory,
@@ -133,7 +133,7 @@ dbus_realloc (void  *memory,
 
 /**
  * Frees a block of memory previously allocated by dbus_malloc() or
- * dbus_malloc0().
+ * dbus_malloc0(). If passed #NULL, does nothing.
  * 
  * @param memory block to be freed
  */

dbus/dbus-memory.h

@@ -28,7 +28,7 @@
 #define DBUS_MEMORY_H
 
 #include <dbus/dbus-macros.h>
-#include <sys/types.h> /* for size_t - is there a better header for this? */
+#include <stddef.h>
 
 DBUS_BEGIN_DECLS
 

dbus/dbus-message.c

@@ -33,9 +33,14 @@
  * @{
  */
 
+/**
+ * @struct DBusMessage
+ * Object representing a message received from or to be sent to
+ * another application.
+ */
 struct DBusMessage
 {
-  int refcount;
+  int refcount; /**< Reference count */
 
 };
 

dbus/dbus-test.c

@@ -0,0 +1,45 @@
+/* -*- mode: C; c-file-style: "gnu" -*- */
+/* dbus-test.c  Program to run all tests
+ *
+ * Copyright (C) 2002  Red Hat Inc.
+ *
+ * Licensed under the Academic Free License version 1.2
+ * 
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *
+ */
+
+#include "dbus-types.h"
+#include <stdio.h>
+
+/* To add a test, write a function like this one,
+ * declare it here, define it in the file to be tested,
+ * then call it from main() below. Test functions
+ * should return FALSE on failure.
+ */
+dbus_bool_t _dbus_hash_test (void);
+
+int
+main (int    argc,
+      char **argv)
+{
+  printf ("%s: running hash table tests\n", argv[0]);
+  if (!_dbus_hash_test ())
+    return 1;
+
+  
+  printf ("%s: completed successfully\n", argv[0]);
+  return 0;
+}

dbus/dbus-test.h

@@ -0,0 +1,31 @@
+/* -*- mode: C; c-file-style: "gnu" -*- */
+/* dbus-test.h  Declarations of test functions.
+ *
+ * Copyright (C) 2002  Red Hat Inc.
+ *
+ * Licensed under the Academic Free License version 1.2
+ * 
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *
+ */
+
+#ifndef DBUS_TEST_H
+#define DBUS_TEST_H
+
+#include <dbus/dbus-types.h>
+
+dbus_bool_t _dbus_hash_test (void);
+
+#endif /* DBUS_TEST_H */

dbus/dbus-types.h

@@ -29,4 +29,7 @@
 
 typedef unsigned int dbus_bool_t;
 
+typedef unsigned int dbus_uint32_t;
+typedef int          dbus_int32_t;
+
 #endif /* DBUS_TYPES_H */

dbus/dbus.h

@@ -28,11 +28,13 @@
 
 #include <dbus/dbus-macros.h>
 #include <dbus/dbus-message.h>
+#include <dbus/dbus-types.h>
 
 #undef DBUS_INSIDE_DBUS_H
 
 /**
- * @defgroup DBus D-BUS message system
+ * @defgroup DBus D-BUS message system public API
+ * @brief The exported public API of the D-BUS library.
  *
  * @{
  */

test/Makefile.am

@@ -0,0 +1,4 @@
+
+if DBUS_BUILD_TESTS
+
+endif