su: updated documentation

Removed internal files from doxygen-generated documentation.

darcs-hash:20070920173656-65a35-ddd22b107b84ee52fdb9ec536caf5d0c658f864c.gz

libsofia-sip-ua/su/memccpy.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**@file memccpy.c
+/**@internal @file memccpy.c
  * @brief The memccpy() replacement function.
  *  
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>

libsofia-sip-ua/su/memcspn.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**@file memcspn.c
+/**@internal @file memcspn.c
  * @brief The memcspn() replacement function.
  *  
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>

libsofia-sip-ua/su/memmem.c

@@ -22,7 +22,8 @@
  *
  */
 
-/**@file memmem.c
+/**@internal @file memmem.c
+ *
  * @brief Backup implementation of memmem()
  *  
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>

libsofia-sip-ua/su/memspn.c

@@ -22,7 +22,8 @@
  *
  */
 
-/**@file memspn.c
+/**@internal @file memspn.c
+ * 
  * The memspn() replacement function.
  *  
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>

libsofia-sip-ua/su/sofia-sip/htable2.h

@@ -31,7 +31,7 @@
  * Hash tables templates, take 2.
  *
  * Note: this version can handle structures as entries, and it can be used
- * without <su_alloc.h>.
+ * without <sofia-sip/su_alloc.h>.
  * 
  * This file contain a hash table template for C.  The hash tables are
  * resizeable, and they usually contain pointers to entries.  The

libsofia-sip-ua/su/sofia-sip/su_config.h

@@ -28,7 +28,7 @@
  * 
  * @b su library configuration
  * 
- * This file includes an appropriate <su_configure*.h> include file.
+ * This file includes an appropriate <sofia-sip/su_configure*.h> include file.
  *
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>
  * 

libsofia-sip-ua/su/sofia-sip/su_os_nw.h

@@ -70,11 +70,11 @@ SOFIA_BEGIN_DECLS
 /**Default type of application context for network_changed function.
  *
  * Application may define the typedef ::su_network_changed_magic_t to appropriate type
- * by defining macro #SU_NETWORK_CHANGED_MAGIC_T before including <su_os_nw.h>, for
+ * by defining macro #SU_NETWORK_CHANGED_MAGIC_T before including <sofia-sip/su_os_nw.h>, for
  * example,
  * @code
  * #define SU_NETWORK_CHANGED_MAGIC_T struct context
- * #include <su_os_nw.h>
+ * #include <sofia-sip/su_os_nw.h>
  * @endcode
  *
  * @since New in @VERSION_1_12_2.
@@ -85,11 +85,11 @@ SOFIA_BEGIN_DECLS
 /** <a href="#su_root_t">Root context</a> pointer type.
  *
  * Application may define the typedef ::su_network_changed_magic_t to appropriate type
- * by defining macro #SU_NETWORK_CHANGED_MAGIC_T before including <su_os_nw.h>, for
+ * by defining macro #SU_NETWORK_CHANGED_MAGIC_T before including <sofia-sip/su_os_nw.h>, for
  * example,
  * @code
  * #define SU_NETWORK_CHANGED_MAGIC_T struct context
- * #include <su_os_nw.h>
+ * #include <sofia-sip/su_os_nw.h>
  * @endcode
  *
  * @since New in @VERSION_1_12_2.

libsofia-sip-ua/su/sofia-sip/su_tag.h

@@ -68,11 +68,17 @@ typedef struct {
 /** Tag type class */
 typedef struct tag_class_s const tag_class_t;
 
+/** Tag structure. 
+ *
+ * The tag structure contains the name, namespace and class of the tag. The
+ * fourth field, @a tt_magic, is interpreted by the tag class.
+ */
 struct tag_type_s {
-  char const    *tt_ns;
-  char const 	*tt_name;
-  tag_class_t   *tt_class;
-  tag_value_t    tt_magic;
+  char const    *tt_ns;		/**< Tag namespace (e.g., "sip" or "nua") */
+  char const 	*tt_name;	/**< Tag name (e.g, "min_se")  */
+  tag_class_t   *tt_class;	/**< Tag class defines the type of the value */
+  tag_value_t    tt_magic;	/**< Class-specific data 
+				   (e.g., pointer to header class structure) */
 };
 
 /** Definition of tag type. */

libsofia-sip-ua/su/sofia-sip/su_tag_class.h

@@ -49,7 +49,7 @@ SOFIA_BEGIN_DECLS
 #endif
 
 #define TAG_TYPEDEF(t, type) \
-  {{ TAG_NAMESPACE, #t, type ## _tag_class }}
+  {{ TAG_NAMESPACE, #t, type ## _tag_class, 0 }}
 
 #define INTTAG_TYPEDEF(t)      TAG_TYPEDEF(t, int)
 #define UINTTAG_TYPEDEF(t)     TAG_TYPEDEF(t, uint)
@@ -63,7 +63,7 @@ SOFIA_BEGIN_DECLS
 #define NSTAG_TYPEDEF(t)       TAG_TYPEDEF(t, ns)
 
 struct tag_class_s {
-  int             tc_size;
+  int             tc_size;	/**< Size of the tag_class_t structure */
   tagi_t const *(*tc_next)(tagi_t const *t);
   size_t        (*tc_len)(tagi_t const *t);
   tagi_t       *(*tc_move)(tagi_t *dst, tagi_t const *src);

libsofia-sip-ua/su/sofia-sip/su_tagarg.h

@@ -43,7 +43,7 @@ SOFIA_BEGIN_DECLS
 /**@page tagarg Tagarg Functions
  *
  * A @em tagarg function may be called with a varying number of tagged
- * arguments.  The include file <su_tagarg.h> declares a type ta_list and
+ * arguments.  The include file <sofia-sip/su_tagarg.h> declares a type ta_list and
  * defines four macros (ta_start(), ta_args(), ta_tags() and ta_end()) for
  * accessing the argument list.
  *
@@ -66,10 +66,11 @@ SOFIA_BEGIN_DECLS
  * TAG_NULL() or TAG_NEXT().
  */
 
-/**Object for accessing tagged argument lists.
+/**Structure for accessing tagged argument lists.
  *
- * The called function must declare an object of type ta_list which is
- * used by the macros ta_start(), ta_args(), ta_tags(), and ta_end().
+ * The function called with tagged arguments must declare an object of type
+ * ta_list which is used by the macros ta_start(), ta_args(), ta_tags(), and
+ * ta_end().
  *
  * If a tagged list is not finished with TAG_END(), TAG_NULL(), or
  * TAG_NEXT() items, random errors may occur.

libsofia-sip-ua/su/sofia-sip/su_time.h

@@ -78,7 +78,7 @@ typedef uint64_t su_ntp_t;
 
 #define SU_TIME_CMP(t1, t2) su_time_cmp(t1, t2)
 
-/** Seconds from 1.1.1900 to 1.1.1970. @NEW_1_12_4 */
+/** Seconds from 1.1.1900 to 1.1.1970. @NEW_1_12_4. */
 #define SU_TIME_EPOCH 2208988800UL 
 
 typedef uint64_t su_nanotime_t;

libsofia-sip-ua/su/sofia-sip/su_types.h

@@ -68,7 +68,7 @@ SOFIA_BEGIN_DECLS
 
 #if DOXYGEN_ONLY || (!SU_HAVE_STDINT && !SU_HAVE_INTTYPES && SU_HAVE_WIN32)
 
-/* Use macros defined in <su_configure_win32.h> */
+/* Use macros defined in <sofia-sip/su_configure_win32.h> */
 
 #ifndef _INTPTR_T_DEFINED
 /** Integer type large enough to store pointers */

libsofia-sip-ua/su/sofia-sip/su_wait.h

@@ -213,11 +213,11 @@ typedef struct su_root_s su_root_t;
 /**Default type of application context for <a href="#su_root_t">su_root_t</a>.
  *
  * Application may define the typedef ::su_root_magic_t to appropriate type
- * by defining macro SU_ROOT_MAGIC_T before including <su_wait.h>, for
+ * by defining macro SU_ROOT_MAGIC_T before including <sofia-sip/su_wait.h>, for
  * example,
  * @code
  * #define SU_ROOT_MAGIC_T struct context
- * #include <su_wait.h>
+f * #include <sofia-sip/su_wait.h>
  * @endcode
  */
 #define SU_ROOT_MAGIC_T void
@@ -226,11 +226,11 @@ typedef struct su_root_s su_root_t;
 /** <a href="#su_root_t">Root context</a> pointer type.
  *
  * Application may define the typedef ::su_root_magic_t to appropriate type
- * by defining macro SU_ROOT_MAGIC_T () before including <su_wait.h>, for
+ * by defining macro SU_ROOT_MAGIC_T () before including <sofia-sip/su_wait.h>, for
  * example,
  * @code
  * #define SU_ROOT_MAGIC_T struct context
- * #include <su_wait.h>
+ * #include <sofia-sip/su_wait.h>
  * @endcode
  */
 typedef SU_ROOT_MAGIC_T su_root_magic_t;
@@ -240,10 +240,10 @@ typedef SU_ROOT_MAGIC_T su_root_magic_t;
  * @link ::su_wakeup_arg_t argument type @endlink.  
  *
  * The application can define the typedef ::su_wakeup_arg_t by defining
- * the SU_WAKEUP_ARG_T () before including <su_wait.h>, for example,
+ * the SU_WAKEUP_ARG_T () before including <sofia-sip/su_wait.h>, for example,
  * @code
  * #define SU_WAKEUP_ARG_T struct transport
- * #include <su_wait.h>
+ * #include <sofia-sip/su_wait.h>
  * @endcode
  */
 #define SU_WAKEUP_ARG_T void
@@ -252,10 +252,10 @@ typedef SU_ROOT_MAGIC_T su_root_magic_t;
 /** @link ::su_wakeup_f Wakeup callback @endlink argument type. 
  *
  * The application can define the typedef ::su_wakeup_arg_t by defining
- * the SU_WAKEUP_ARG_T () before including <su_wait.h>, for example,
+ * the SU_WAKEUP_ARG_T () before including <sofia-sip/su_wait.h>, for example,
  * @code
  * #define SU_WAKEUP_ARG_T struct transport
- * #include <su_wait.h>
+ * #include <sofia-sip/su_wait.h>
  * @endcode
  */
 typedef SU_WAKEUP_ARG_T su_wakeup_arg_t;
@@ -287,11 +287,11 @@ SOFIAPUBVAR int su_root_size_hint;
 /**Default type of application context for prepoll function.
  *
  * Application may define the typedef ::su_prepoll_magic_t to appropriate type
- * by defining macro #SU_PREPOLL_MAGIC_T before including <su_wait.h>, for
+ * by defining macro #SU_PREPOLL_MAGIC_T before including <sofia-sip/su_wait.h>, for
  * example,
  * @code
  * #define SU_PREPOLL_MAGIC_T struct context
- * #include <su_wait.h>
+ * #include <sofia-sip/su_wait.h>
  * @endcode
  */
 #define SU_PREPOLL_MAGIC_T void
@@ -300,11 +300,11 @@ SOFIAPUBVAR int su_root_size_hint;
 /** <a href="#su_root_t">Root context</a> pointer type.
  *
  * Application may define the typedef ::su_prepoll_magic_t to appropriate type
- * by defining macro #SU_PREPOLL_MAGIC_T before including <su_wait.h>, for
+ * by defining macro #SU_PREPOLL_MAGIC_T before including <sofia-sip/su_wait.h>, for
  * example,
  * @code
  * #define SU_PREPOLL_MAGIC_T struct context
- * #include <su_wait.h>
+ * #include <sofia-sip/su_wait.h>
  * @endcode
  */
 typedef SU_PREPOLL_MAGIC_T su_prepoll_magic_t;
@@ -326,7 +326,7 @@ typedef void su_prepoll_f(su_prepoll_magic_t *, su_root_t *);
 #ifndef SU_TIMER_ARG_T
 /** Default type of timer expiration callback function argument type.
  * Application may define this to appropriate type before including
- * <su_wait.h>. */
+ * <sofia-sip/su_wait.h>. */
 #define SU_TIMER_ARG_T void 
 #endif
 
@@ -370,7 +370,7 @@ typedef _su_task_t const *_su_task_r;
 /* Messages */
 #ifndef SU_MSG_ARG_T
 /** Default type of su_msg_t message data.  Application may define this to
- * appropriate type before including <su_wait.h>.
+ * appropriate type before including <sofia-sip/su_wait.h>.
  */
 #define SU_MSG_ARG_T void 
 #endif

libsofia-sip-ua/su/strcasestr.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**@file strcasestr.c
+/**@internal @file strcasestr.c
  * @brief Backup implementation of strcasestr()
  *  
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>

libsofia-sip-ua/su/su_alloc.c

@@ -22,14 +22,6 @@
  *
  */
 
-/**@ingroup su_alloc
- * @CFILE su_alloc.c  Home-based memory management.
- *
- * @author Pekka Pessi <Pekka.Pessi@nokia.com>.
- * 
- * @date Created: Thu Aug 19 01:12:25 1999 ppessi
- */
-
 #include "config.h"
 
 /**@defgroup su_alloc Memory Management Tutorial
@@ -181,6 +173,14 @@
  * where the stack frame used in su_home_auto() was allocated.
  */
 
+/**@ingroup su_alloc
+ * @CFILE su_alloc.c  Home-based memory management.
+ *
+ * @author Pekka Pessi <Pekka.Pessi@nokia.com>.
+ * 
+ * @date Created: Thu Aug 19 01:12:25 1999 ppessi
+ */
+
 #include <sofia-sip/su_config.h>
 #include "sofia-sip/su_alloc.h"
 #include "sofia-sip/su_alloc_stat.h"

libsofia-sip-ua/su/su_bm.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**
+/**@internal
  * @file su_bm.c
  * @brief Search with Boyer-Moore algorithm
  *  

libsofia-sip-ua/su/su_module_debug.h

@@ -27,7 +27,7 @@
 #define SU_MODULE_DEBUG_H
 
 /**@ingroup su_log
- * @file su_module_debug.h
+ * @internal @file su_module_debug.h
  * @brief Debug log for @b su module
  *
  * The su_module_debug.h defines a common debug log #su_log_global for all

libsofia-sip-ua/su/su_port.h

@@ -26,7 +26,7 @@
 /** Defined when <su_port.h> has been included. */
 #define SU_PORT_H
 
-/**@IFILE su_port.h 
+/**@internal @file su_port.h 
  *
  * @brief Internal OS-independent syncronization interface.
  *
@@ -59,7 +59,7 @@
 
 SOFIA_BEGIN_DECLS
 
-/** Message */
+/** @internal Message */
 struct su_msg_s {
   isize_t        sum_size;
   su_msg_t      *sum_next;
@@ -72,7 +72,7 @@ struct su_msg_s {
 
 struct _GSource;
 
-/** Root structure */
+/** @internal Root structure */
 struct su_root_s {
   int              sur_size;
   su_root_magic_t *sur_magic;
@@ -85,7 +85,7 @@ struct su_root_s {
 
 #define SU_ROOT_MAGIC(r) ((r) ? (r)->sur_magic : NULL)
 
-/** Virtual function table for port */
+/** @internal Virtual function table for port */
 typedef struct su_port_vtable {
   unsigned su_vtable_size;
   void (*su_port_lock)(su_port_t *port, char const *who);
@@ -423,7 +423,7 @@ SOFIAPUBFUN int su_port_execute(su_task_r const task,
 
 /* ---------------------------------------------------------------------- */
 
-/** Base port object.
+/**@internal Base port object.
  *
  * Port is a per-thread reactor. Multiple root objects executed by a single
  * thread share the su_port_t object.
@@ -502,7 +502,7 @@ SOFIAPUBFUN void su_base_port_wait(su_clone_r rclone);
 
 #include <pthread.h>
 
-/** Pthread port object */ 
+/** @internal Pthread port object */ 
 typedef struct su_pthread_port_s {
   su_base_port_t   sup_base[1];
   struct su_pthread_port_waiting_parent 

libsofia-sip-ua/su/su_proxy.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**@ingroup su_root_ex
+/**@internal @ingroup su_root_ex
  *
  * @file su_proxy.c 
  *

libsofia-sip-ua/su/su_root.c

@@ -458,7 +458,7 @@ void su_root_destroy(su_root_t *self)
  *
  * @return Instance name (e.g., "epoll", "devpoll", "select").
  *
- * @NEW_1_12_6
+ * @NEW_1_12_6.
  */
 char const *su_root_name(su_root_t *self)
 {

libsofia-sip-ua/su/su_taglist.c

@@ -1299,7 +1299,7 @@ int t_size_scan(tag_type_t tt, su_home_t *home,
   }
 }
 
-/** Tag class for tags with size_t value. @NEW_1_12_5 */
+/** Tag class for tags with size_t value. @NEW_1_12_5. */
 tag_class_t size_tag_class[1] = 
   {{
     sizeof(int_tag_class),
@@ -1347,7 +1347,7 @@ int t_usize_scan(tag_type_t tt, su_home_t *home,
   }
 }
 
-/** Tag class for tags with usize_t value. @NEW_1_12_5 */
+/** Tag class for tags with usize_t value. @NEW_1_12_5. */
 tag_class_t usize_tag_class[1] = 
   {{
     sizeof(int_tag_class),

libsofia-sip-ua/su/test_poll.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**@ingroup su_root_ex
+/**@internal 
  * @file test_poll.c
  * Example code for <sofia-sip/su_wait.h>.
  *

libsofia-sip-ua/su/torture_heap.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**
+/**@internal
  * @file torture_heap.c
  * @brief Test heap
  *

libsofia-sip-ua/su/torture_rbtree.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**
+/**@internal
  * @file torture_rbtree.c
  * @brief Test red-black tree
  *

libsofia-sip-ua/su/torture_su.c

@@ -22,8 +22,7 @@
  *
  */
 
-/**@ingroup su
- * 
+/**@internal
  * @file torture_su.c
  *
  * Testing functions for su socket functions.

libsofia-sip-ua/su/torture_su_alloc.c

@@ -22,8 +22,7 @@
  *
  */
 
-/**@ingroup su_alloc
- *
+/**@internal 
  * @file su_alloc_test.c
  *
  * Testing functions for su_alloc functions.

libsofia-sip-ua/su/torture_su_bm.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**
+/**@internal
  * @file torture_su_bm.c
  * @brief Test string search with Boyer-Moore algorithm 
  *  

libsofia-sip-ua/su/torture_su_port.c

@@ -22,7 +22,7 @@
  *
  */
 
-/**
+/**@internal
  * @file torture_su_port.c
  * @brief Test su_poll_port interface
  *

libsofia-sip-ua/su/torture_su_root.c

@@ -22,8 +22,7 @@
  *
  */
 
-/**@ingroup su_root_ex
- * 
+/**@internal
  * @file torture_su_root.c
  *
  * Test su_root_register functionality.

libsofia-sip-ua/su/torture_su_root_osx.c

@@ -22,8 +22,7 @@
  *
  */
 
-/**@ingroup su_root_ex
- * 
+/**@internal
  * @file torture_su_root_osx.c
  *
  * Test su_root_register functionality.

libsofia-sip-ua/su/torture_su_tag.c

@@ -22,8 +22,7 @@
  *
  */
 
-/**@SU_TAG
- * 
+/**@internal
  * @file torture_su_tag.c
  *
  * Testing functions for su_tag module.