A lot of doxygen updates
authorOlle Johansson <oej@edvina.net>
Tue, 11 Dec 2007 14:17:29 +0000 (14:17 +0000)
committerOlle Johansson <oej@edvina.net>
Tue, 11 Dec 2007 14:17:29 +0000 (14:17 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@92285 65c4cc65-6c06-0410-ace0-fbb531ad65f3

23 files changed:
include/asterisk/_private.h
include/asterisk/adsi.h
include/asterisk/ael_structs.h
include/asterisk/aes.h
include/asterisk/agi.h
include/asterisk/alaw.h
include/asterisk/app.h
include/asterisk/ast_expr.h
include/asterisk/astdb.h
include/asterisk/astobj2.h
include/asterisk/callerid.h
include/asterisk/causes.h
include/asterisk/cdr.h
include/asterisk/devicestate.h
include/asterisk/doxyref.h
include/asterisk/dsp.h
include/asterisk/event.h
include/asterisk/extconf.h
include/asterisk/hashtab.h
include/asterisk/io.h
include/asterisk/localtime.h
include/asterisk/logger.h
include/asterisk/mod_format.h

index a936bea..06163cd 100644 (file)
@@ -4,6 +4,14 @@
  * What goes here are typically *_init() routines.
  */
 
+/*! \file
+ *
+ * \brief
+ * Prototypes for public functions only of internal interest,
+ * 
+ */
+
+
 #ifndef _ASTERISK__PRIVATE_H
 #define _ASTERISK__PRIVATE_H
 
index c4379dc..3c31574 100644 (file)
@@ -24,6 +24,8 @@
 #define _ASTERISK_ADSI_H
 
 #include "asterisk/callerid.h"
+/*! \name ADSI parameters */
+/*@{ */
 
 /* ADSI Message types */
 #define ADSI_MSG_DISPLAY       132
 #define ADSI_DIR_FROM_LEFT (0)
 #define ADSI_DIR_FROM_RIGHT (1)
 
+/*@} */
+
 /*! Perform Asterisk ADSI initialization (for channel drivers that want 
  *    to support ADSI when the handset is first lifted) 
  * \param chan Channel to initialize for ADSI (if supported)
index fa551bf..0a58ed3 100644 (file)
@@ -20,6 +20,7 @@
  * \brief Structures for AEL - the Asterisk extension language
  *
  * \ref pbx_ael.c
+ * \todo document this file (ael.h)
  */
 
 #ifndef _ASTERISK_AEL_STRUCTS_H
@@ -113,8 +114,8 @@ struct ael_extension
        struct ael_priority *plist_last;
        struct ael_extension *next_exten;
 
-       struct ael_priority *loop_break;  /* set by latest loop for breaks */
-       struct ael_priority *loop_continue; /* set by lastest loop for continuing */
+       struct ael_priority *loop_break;  /*!< set by latest loop for breaks */
+       struct ael_priority *loop_continue; /*!< set by lastest loop for continuing */
        struct ael_priority *return_target;
        int return_needed;
 };
index bf79968..25e7615 100644 (file)
@@ -17,7 +17,9 @@
  */
 
 /*! \file
- * \brief Wrappers for AES encryption/decryption
+ * Wrappers for AES encryption/decryption
+ *
+ * \author Kevin P. Fleming <kpfleming@digium.com>
  *
  * These wrappers provided a generic interface to either the
  * AES methods provided by OpenSSL's crypto library, or the
index 1d86ac9..5085f05 100644 (file)
@@ -28,11 +28,11 @@ extern "C" {
 #endif
 
 typedef struct agi_state {
-       int fd;         /* FD for general output */
-       int audio;      /* FD for audio output */
-       int ctrl;               /* FD for input control */
-       unsigned int fast:1; /* flag for fast agi or not */
-       struct ast_speech *speech; /* Speech structure for speech recognition */
+       int fd;                 /*!< FD for general output */
+       int audio;              /*!< FD for audio output */
+       int ctrl;               /*!< FD for input control */
+       unsigned int fast:1;    /*!< flag for fast agi or not */
+       struct ast_speech *speech; /*!< Speech structure for speech recognition */
 } AGI;
 
 typedef struct agi_command {
index 3496896..0ef42be 100644 (file)
@@ -24,8 +24,7 @@
 #define _ASTERISK_ALAW_H
 
 
-/*! Init the ulaw conversion stuff */
-/*!
+/*! \brief
  * To init the alaw to slinear conversion stuff, this needs to be run.
  */
 void ast_alaw_init(void);
@@ -37,9 +36,7 @@ void ast_alaw_init(void);
 #define AST_ALAW_AMI_MASK  0x55
 
 
-/*! converts signed linear to alaw */
-/*!
- */
+/*! \brief converts signed linear to alaw */
 #ifndef G711_NEW_ALGORITHM
 extern unsigned char __ast_lin2a[8192];
 #else
@@ -55,7 +52,7 @@ extern short __ast_alaw[256];
 #define AST_LIN2A_LOOKUP(mag)                                                  \
        __ast_lin2a[(mag) >> AST_ALAW_BIT_LOSS]
 
-/*! convert signed linear sample to sign-magnitude pair for a-Law */
+/*! \brief Convert signed linear sample to sign-magnitude pair for a-Law */
 static inline void ast_alaw_get_sign_mag(short sample, unsigned *sign, unsigned *mag)
 {
        /* It may look illogical to retrive the sign this way in both cases,
index f76b0d9..26523d4 100644 (file)
@@ -17,7 +17,7 @@
 
 /*! \file
  * \brief Application convenience functions, designed to give consistent
- look and feel to Asterisk apps.
+ *        look and feel to Asterisk apps.
  */
 
 #ifndef _ASTERISK_APP_H
@@ -109,16 +109,16 @@ void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, con
   
 void ast_uninstall_vm_functions(void);
 
-/*! Determine if a given mailbox has any voicemail */
+/*! \brief Determine if a given mailbox has any voicemail */
 int ast_app_has_voicemail(const char *mailbox, const char *folder);
 
-/*! Determine number of new/old messages in a mailbox */
+/*! \brief Determine number of new/old messages in a mailbox */
 int ast_app_inboxcount(const char *mailbox, int *newmsgs, int *oldmsgs);
 
-/*! Determine number of messages in a given mailbox and folder */
+/*! \brief Determine number of messages in a given mailbox and folder */
 int ast_app_messagecount(const char *context, const char *mailbox, const char *folder);
 
-/*! Safely spawn an external program while closing file descriptors 
+/*! \brief Safely spawn an external program while closing file descriptors 
        \note This replaces the \b system call in all Asterisk modules
 */
 int ast_safe_system(const char *s);
@@ -163,7 +163,7 @@ void ast_unreplace_sigchld(void);
 */
 int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration);
 
-/*! Stream a filename (or file descriptor) as a generator. */
+/*! \brief Stream a filename (or file descriptor) as a generator. */
 int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);
 
 /*! 
@@ -171,6 +171,7 @@ int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, in
  * \param chan 
  * \param file filename
  * \param fwd, rev, stop, pause, restart, skipms, offsetms 
+ *
  * Before calling this function, set this to be the number 
  * of ms to start from the beginning of the file.  When the function
  * returns, it will be the number of ms from the beginning where the
@@ -178,23 +179,21 @@ int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, in
  */
 int ast_control_streamfile(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms);
 
-/*! Play a stream and wait for a digit, returning the digit that was pressed */
+/*! \brief Play a stream and wait for a digit, returning the digit that was pressed */
 int ast_play_and_wait(struct ast_channel *chan, const char *fn);
 
 int ast_play_and_record_full(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf);
 
-/*! Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum 
+/*! \brief Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum 
  \n
  permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. 
      calls ast_unlock_path() on 'path' if passed */
 int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path);
 
-/*! Record a message and prepend the message to the given record file after 
+/*! \brief Record a message and prepend the message to the given record file after 
     playing the optional playfile (or a beep), storing the duration in 
-    'duration' and with a maximum  
-\n
-  permitted silence time in milliseconds of 'maxsilence' under 
-  'silencethreshold' or use '-1' for either or both parameters for defaults. */
+    'duration' and with a maximum permitted silence time in milliseconds of 'maxsilence' under 
+    'silencethreshold' or use '-1' for either or both parameters for defaults. */
 int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int beep, int silencethreshold, int maxsilence_ms);
 
 enum AST_LOCK_RESULT {
@@ -223,42 +222,42 @@ void ast_set_lock_type(enum AST_LOCK_TYPE type);
  */
 enum AST_LOCK_RESULT ast_lock_path(const char *path);
 
-/*! Unlock a path */
+/*! \brief Unlock a path */
 int ast_unlock_path(const char *path);
 
-/*! Read a file into asterisk*/
+/*! \brief Read a file into asterisk*/
 char *ast_read_textfile(const char *file);
 
 struct ast_group_info;
 
-/*! Split a group string into group and category, returning a default category if none is provided. */
+/*! \brief Split a group string into group and category, returning a default category if none is provided. */
 int ast_app_group_split_group(const char *data, char *group, int group_max, char *category, int category_max);
 
-/*! Set the group for a channel, splitting the provided data into group and category, if specified. */
+/*! \brief Set the group for a channel, splitting the provided data into group and category, if specified. */
 int ast_app_group_set_channel(struct ast_channel *chan, const char *data);
 
-/*! Get the current channel count of the specified group and category. */
+/*! \brief Get the current channel count of the specified group and category. */
 int ast_app_group_get_count(const char *group, const char *category);
 
-/*! Get the current channel count of all groups that match the specified pattern and category. */
+/*! \brief Get the current channel count of all groups that match the specified pattern and category. */
 int ast_app_group_match_get_count(const char *groupmatch, const char *category);
 
-/*! Discard all group counting for a channel */
+/*! \brief Discard all group counting for a channel */
 int ast_app_group_discard(struct ast_channel *chan);
 
-/*! Update all group counting for a channel to a new one */
+/*! \brief Update all group counting for a channel to a new one */
 int ast_app_group_update(struct ast_channel *oldchan, struct ast_channel *newchan);
 
-/*! Write Lock the group count list */
+/*! \brief Write Lock the group count list */
 int ast_app_group_list_wrlock(void);
 
-/*! Read Lock the group count list */
+/*! \brief Read Lock the group count list */
 int ast_app_group_list_rdlock(void);
 
-/*! Get the head of the group count list */
+/*! \brief Get the head of the group count list */
 struct ast_group_info *ast_app_group_list_head(void);
 
-/*! Unlock the group count list */
+/*! \brief Unlock the group count list */
 int ast_app_group_list_unlock(void);
 
 /*!
@@ -451,10 +450,10 @@ int ast_app_parse_options64(const struct ast_app_option *options, struct ast_fla
 \note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
 int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);
 
-/*! Allow to record message and have a review option */
+/*! \brief Allow to record message and have a review option */
 int ast_record_review(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path);
 
-/*! Decode an encoded control or extended ASCII character */
+/*! \brief Decode an encoded control or extended ASCII character */
 int ast_get_encoded_char(const char *stream, char *result, size_t *consumed);
 
 #if defined(__cplusplus) || defined(c_plusplus)
index c478281..a89b7b9 100644 (file)
  * at the top of the source tree.
  */
 
+/*! \file
+ *  
+ *      ???????  
+ *     \todo Explain this file!
+ */
+
+
 #ifndef _ASTERISK_EXPR_H
 #define _ASTERISK_EXPR_H
 #ifndef STANDALONE
index 887d9af..e19784b 100644 (file)
@@ -33,16 +33,22 @@ struct ast_db_entry {
        char data[0];
 };
 
+/*! \brief Get key value specified by family/key */
 int ast_db_get(const char *family, const char *key, char *out, int outlen);
 
+/*! \brief Store value addressed by family/key*/
 int ast_db_put(const char *family, const char *key, const char *value);
 
+/*! \brief Delete entry in astdb */
 int ast_db_del(const char *family, const char *key);
 
+/*! \brief Delete a whole family (for some reason also called "tree" */
 int ast_db_deltree(const char *family, const char *keytree);
 
+/*! \brief Get a whole family */
 struct ast_db_entry *ast_db_gettree(const char *family, const char *keytree);
 
+/*! \brief Free in-memory data */
 void ast_db_freetree(struct ast_db_entry *entry);
 
 #if defined(__cplusplus) || defined(c_plusplus)
index c19ab68..b02b6cb 100644 (file)
@@ -18,8 +18,9 @@
 #define _ASTERISK_ASTOBJ2_H
 
 /*! \file 
+ * \ref AstObj2
  *
- * \brief Object Model implementing objects and containers.
+ * \page AstObj2 Object Model implementing objects and containers.
 
 This module implements an abstraction for objects (with locks and
 reference counts), and containers for these user-defined objects,
@@ -28,7 +29,7 @@ also supporting locking, reference counting and callbacks.
 The internal implementation of objects and containers is opaque to the user,
 so we can use different data structures as needs arise.
 
-USAGE - OBJECTS
+\section AstObj2_UsageObjects USAGE - OBJECTS
 
 An ao2 object is a block of memory that the user code can access,
 and for which the system keeps track (with a bit of help from the
@@ -53,21 +54,21 @@ The value returned points to the user-visible portion of the objects
 operations such as refcount and lock manipulations.
 
 On return from ao2_alloc():
-- the object has a refcount = 1;
 
-- the memory for the object is allocated dynamically and zeroed;
-
-- we cannot realloc() the object itself;
-
-- we cannot call free(o) to dispose of the object. Rather, we
-  tell the system that we do not need the reference anymore:
+ - the object has a refcount = 1;
+ - the memory for the object is allocated dynamically and zeroed;
+ - we cannot realloc() the object itself;
+ - we cannot call free(o) to dispose of the object. Rather, we
+   tell the system that we do not need the reference anymore:
 
     ao2_ref(o, -1)
 
   causing the destructor to be called (and then memory freed) when
   the refcount goes to 0. This is also available as ao2_unref(o),
   and returns NULL as a convenience, so you can do things like
+
        o = ao2_unref(o);
+
   and clean the original pointer to prevent errors.
 
 - ao2_ref(o, +1) can be used to modify the refcount on the
@@ -77,7 +78,7 @@ On return from ao2_alloc():
   to manipulate the lock associated with the object.
 
 
-USAGE - CONTAINERS
+\section AstObj2_UsageContainers USAGE - CONTAINERS
 
 An ao2 container is an abstract data structure where we can store
 ao2 objects, search them (hopefully in an efficient way), and iterate
@@ -94,7 +95,9 @@ parameters. At the moment, this is done as follows:
 
     c = ao2_container_alloc(MAX_BUCKETS, my_hash_fn, my_cmp_fn);
     \endcode
+
 where
+
 - MAX_BUCKETS is the number of buckets in the hash table,
 - my_hash_fn() is the (user-supplied) function that returns a
   hash key for the object (further reduced modulo MAX_BUCKETS
@@ -129,9 +132,12 @@ reinserting it after the change (this is not terribly expensive).
 \note A container with a single buckets is effectively a linked
 list. However there is no ordering among elements.
 
+- \ref AstObj2_Containers
+- \ref astobj2.h All documentation for functions and data structures
+
  */
 
-/*!
+/*! \brief
  * Typedef for an object destructor. This is called just before freeing
  * the memory for the object. It is passed a pointer to the user-defined
  * data of the object.
@@ -139,7 +145,7 @@ list. However there is no ordering among elements.
 typedef void (*ao2_destructor_fn)(void *);
 
 
-/*!
+/*! \brief
  * Allocate and initialize an object.
  * 
  * \param data_size The sizeof() of the user-defined structure.
@@ -156,7 +162,7 @@ typedef void (*ao2_destructor_fn)(void *);
  */
 void *ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
 
-/*!
+/*! \brief
  * Reference/unreference an object and return the old refcount.
  *
  * \param o A pointer to the object
@@ -178,7 +184,7 @@ void *ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
  */
 int ao2_ref(void *o, int delta);
 
-/*!
+/*! \brief
  * Lock an object.
  * 
  * \param a A pointer to the object we want lock.
@@ -186,7 +192,7 @@ int ao2_ref(void *o, int delta);
  */
 int ao2_lock(void *a);
 
-/*!
+/*! \brief
  * Unlock an object.
  * 
  * \param a A pointer to the object we want unlock.
@@ -194,31 +200,31 @@ int ao2_lock(void *a);
  */
 int ao2_unlock(void *a);
 
-/*!
+/*! 
  *
- * Containers
+ \page AstObj2_Containers AstObj2 Containers
 
 Containers are data structures meant to store several objects,
 and perform various operations on them.
 Internally, objects are stored in lists, hash tables or other
 data structures depending on the needs.
 
-NOTA BENE: at the moment the only container we support is the
-hash table and its degenerate form, the list.
+\note NOTA BENE: at the moment the only container we support is the
+       hash table and its degenerate form, the list.
 
 Operations on container include:
 
-    c = ao2_container_alloc(size, cmp_fn, hash_fn)
+  -  c = \b ao2_container_alloc(size, cmp_fn, hash_fn)
        allocate a container with desired size and default compare
        and hash function
 
-    ao2_find(c, arg, flags)
+  -  \b ao2_find(c, arg, flags)
        returns zero or more element matching a given criteria
        (specified as arg). Flags indicate how many results we
        want (only one or all matching entries), and whether we
        should unlink the object from the container.
 
-    ao2_callback(c, flags, fn, arg)
+  -  \b ao2_callback(c, flags, fn, arg)
        apply fn(obj, arg) to all objects in the container.
        Similar to find. fn() can tell when to stop, and
        do anything with the object including unlinking it.
@@ -231,9 +237,11 @@ Operations on container include:
        can do basically anything e.g. counting, deleting records, etc.
        possibly using arg to store the results.
    
-    iterate on a container
+  -  \b iterate on a container
        this is done with the following sequence
 
+\code
+
            struct ao2_container *c = ... // our container
            struct ao2_iterator i;
            void *o;
@@ -244,38 +252,40 @@ Operations on container include:
                ... do something on o ...
                ao2_ref(o, -1);
            }
+\endcode
 
        The difference with the callback is that the control
        on how to iterate is left to us.
 
-    ao2_ref(c, -1)
+    - \b ao2_ref(c, -1)
        dropping a reference to a container destroys it, very simple!
  
 Containers are ao2 objects themselves, and this is why their
 implementation is simple too.
 
- */
+Before declaring containers, we need to declare the types of the
+arguments passed to the constructor - in turn, this requires
+to define callback and hash functions and their arguments.
 
-/*!
- * Before declaring containers, we need to declare the types of the
- * arguments passed to the constructor - in turn, this requires
- * to define callback and hash functions and their arguments.
+- \ref AstObj2
+- \ref astobj2.h
  */
 
-/*!
+/*! \brief
  * Type of a generic callback function
  * \param obj  pointer to the (user-defined part) of an object.
  * \param arg callback argument from ao2_callback()
  * \param flags flags from ao2_callback()
+ *
  * The return values are a combination of enum _cb_results.
  * Callback functions are used to search or manipulate objects in a container,
  */
 typedef int (ao2_callback_fn)(void *obj, void *arg, int flags);
 
-/*! a very common callback is one that matches by address. */
+/*! \brief a very common callback is one that matches by address. */
 ao2_callback_fn ao2_match_by_addr;
 
-/*!
+/*! \brief
  * A callback function will return a combination of CMP_MATCH and CMP_STOP.
  * The latter will terminate the search in a container.
  */
@@ -284,7 +294,7 @@ enum _cb_results {
        CMP_STOP        = 0x2,  /*!< stop the search now */
 };
 
-/*!
+/*! \brief
  * Flags passed to ao2_callback() and ao2_hash_fn() to modify its behaviour.
  */
 enum search_flags {
@@ -312,12 +322,13 @@ enum search_flags {
  */
 typedef int (ao2_hash_fn)(const void *obj, const int flags);
 
-/*!
+/*! \name Object Containers 
  * Here start declarations of containers.
  */
+/*@{ */
 struct ao2_container;
 
-/*!
+/*! \brief
  * Allocate and initialize a container 
  * with the desired number of buckets.
  * 
@@ -335,17 +346,19 @@ struct ao2_container;
 struct ao2_container *ao2_container_alloc(const uint n_buckets,
                ao2_hash_fn *hash_fn, ao2_callback_fn *cmp_fn);
 
-/*!
+/*! \brief
  * Returns the number of elements in a container.
  */
 int ao2_container_count(struct ao2_container *c);
+/*@} */
 
-/*
+/*! \name Object Management
  * Here we have functions to manage objects.
  *
  * We can use the functions below on any kind of 
  * object defined by the user.
  */
+/*@{ */
 
 /*!
  * \brief Add an object to a container.
@@ -387,8 +400,9 @@ struct ao2_list {
        struct ao2_list *next;
        void *obj;      /* pointer to the user portion of the object */
 };
+/*@} */
 
-/*!
+/*! \brief
  * ao2_callback() is a generic function that applies cb_fn() to all objects
  * in a container, as described below.
  * 
@@ -400,6 +414,7 @@ struct ao2_list {
  * \return     A pointer to the object found/marked, 
  *             a pointer to a list of objects matching comparison function,
  *             NULL if not found.
+ *
  * If the function returns any objects, their refcount is incremented,
  * and the caller is in charge of decrementing them once done.
  * Also, in case of multiple values returned, the list used
@@ -453,7 +468,7 @@ void *ao2_callback(struct ao2_container *c,
  */
 void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
 
-/*!
+/*! \brief
  *
  *
  * When we need to walk through a container, we use
@@ -502,8 +517,10 @@ void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
  *
  */
 
-/*!
- * You are not supposed to know the internals of an iterator!
+/*! \brief 
+ * The Astobj2 iterator
+ *
+ * \note You are not supposed to know the internals of an iterator!
  * We would like the iterator to be opaque, unfortunately
  * its size needs to be known if we want to store it around
  * without too much trouble.
@@ -513,6 +530,7 @@ void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
  * should be locked or not while navigating on it.
  * The iterator "points" to the current object, which is identified
  * by three values:
+ *
  * - a bucket number;
  * - the object_id, which is also the container version number
  *   when the object was inserted. This identifies the object
@@ -521,10 +539,10 @@ void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
  * - a pointer, and a container version when we saved the pointer.
  *   If the container has not changed its version number, then we
  *   can safely follow the pointer to reach the object in constant time.
+ *
  * Details are in the implementation of ao2_iterator_next()
  * A freshly-initialized iterator has bucket=0, version = 0.
  */
-
 struct ao2_iterator {
        /*! the container */
        struct ao2_container *c;
index b7568c2..8bf2715 100644 (file)
@@ -20,6 +20,8 @@
  * \brief CallerID (and other GR30) management and generation
  * Includes code and algorithms from the Zapata library.
  *
+ * \ref CID
+ *
  */
 
 /*!
index ad3fa67..fb4f3c1 100644 (file)
@@ -85,7 +85,11 @@ For more information:
 - \ref app_dial.c
 */
 
-/* Causes for disconnection (from Q.931) */
+/*! \name Causes for disconnection (from Q.931) 
+       These are the internal cause codes used in Asterisk.
+       \ref AstCauses
+*/
+/*@{ */
 #define AST_CAUSE_UNALLOCATED                          1
 #define AST_CAUSE_NO_ROUTE_TRANSIT_NET                 2
 #define AST_CAUSE_NO_ROUTE_DESTINATION                 3
@@ -140,5 +144,6 @@ For more information:
 #define AST_CAUSE_UNREGISTERED                         AST_CAUSE_NO_ROUTE_DESTINATION
 #define AST_CAUSE_NOTDEFINED                           0
 #define AST_CAUSE_NOSUCHDRIVER                         AST_CAUSE_CHAN_NOT_IMPLEMENTED
+/*@{ */
 
 #endif /* _ASTERISK_CAUSES_H */
index b2307e5..96a5dc4 100644 (file)
 #define AST_CDR_FLAG_CHILD                     (1 << 3)
 #define AST_CDR_FLAG_POST_DISABLED             (1 << 4)
 
+/*! \name CDR Flags */
+/*@{ */
 #define AST_CDR_NULL                0
 #define AST_CDR_FAILED                         (1 << 0)
 #define AST_CDR_BUSY                           (1 << 1)
 #define AST_CDR_NOANSWER                       (1 << 2)
 #define AST_CDR_ANSWERED                       (1 << 3)
+/*@} */
 
-/*! AMA Flags */
+/*! \name CDR AMA Flags */
+/*@{ */
 #define AST_CDR_OMIT                           (1)
 #define AST_CDR_BILLING                                (2)
 #define AST_CDR_DOCUMENTATION                  (3)
+/*@} */
 
 #define AST_MAX_USER_FIELD                     256
 #define AST_MAX_ACCOUNT_CODE                   20
@@ -48,7 +53,7 @@
 #include "asterisk/channel.h"
 #include "asterisk/utils.h"
 
-/*! Responsible for call detail data */
+/*! \brief Responsible for call detail data */
 struct ast_cdr {
        /*! Caller*ID with text */
        char clid[AST_MAX_EXTENSION];
@@ -298,11 +303,15 @@ char *ast_cdr_flags2str(int flags);
  */
 void ast_cdr_merge(struct ast_cdr *to, struct ast_cdr *from);
 
+/*! \brief Set account code, will generate AMI event */
 int ast_cdr_setaccount(struct ast_channel *chan, const char *account);
-int ast_cdr_setamaflags(struct ast_channel *chan, const char *amaflags);
 
+/*! \brief Set AMA flags for channel */
+int ast_cdr_setamaflags(struct ast_channel *chan, const char *amaflags);
 
+/*! \brief Set CDR user field for channel (stored in CDR) */
 int ast_cdr_setuserfield(struct ast_channel *chan, const char *userfield);
+/*! \brief Append to CDR user field for channel (stored in CDR) */
 int ast_cdr_appenduserfield(struct ast_channel *chan, const char *userfield);
 
 
@@ -316,10 +325,10 @@ extern char ast_default_accountcode[AST_MAX_ACCOUNT_CODE];
 
 struct ast_cdr *ast_cdr_append(struct ast_cdr *cdr, struct ast_cdr *newcdr);
 
-/*! Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
+/*! \brief Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
 int ast_cdr_engine_reload(void);
 
-/*! Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
+/*! \brief Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
 int ast_cdr_engine_init(void);
 
 /*! Submit any remaining CDRs and prepare for shutdown */
index 68eedcf..d524303 100644 (file)
@@ -41,7 +41,7 @@
 extern "C" {
 #endif
 
-/*! Device States 
+/*! \brief Device States 
  *  \note The order of these states may not change because they are included
  *        in Asterisk events which may be transmitted across the network to
  *        other servers.
index d399ecc..6e4b0e9 100644 (file)
@@ -350,7 +350,6 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \arg Implemented in \ref chan_h323.c
  * \section h323conf h323.conf
  * \ref chan_h323.c
- * \verbinclude h323.txt
  */
 
 /*! \page Config_oss OSS configuration
index b34701f..2664b9b 100644 (file)
 #define DSP_FEATURE_DTMF_DETECT                (1 << 3)
 #define DSP_FEATURE_FAX_DETECT         (1 << 4)
 
-#define        DSP_DIGITMODE_DTMF                      0                               /* Detect DTMF digits */
-#define DSP_DIGITMODE_MF                       1                               /* Detect MF digits */
-
-#define DSP_DIGITMODE_NOQUELCH         (1 << 8)                /* Do not quelch DTMF from in-band */
-#define DSP_DIGITMODE_MUTECONF         (1 << 9)                /* Mute conference */
-#define DSP_DIGITMODE_MUTEMAX          (1 << 10)               /* Delay audio by a frame to try to extra quelch */
-#define DSP_DIGITMODE_RELAXDTMF                (1 << 11)               /* "Radio" mode (relaxed DTMF) */
-
-#define DSP_PROGRESS_TALK              (1 << 16)               /* Enable talk detection */
-#define DSP_PROGRESS_RINGING           (1 << 17)               /* Enable calling tone detection */
-#define DSP_PROGRESS_BUSY              (1 << 18)               /* Enable busy tone detection */
-#define DSP_PROGRESS_CONGESTION                (1 << 19)               /* Enable congestion tone detection */
+#define        DSP_DIGITMODE_DTMF                      0                               /*!< Detect DTMF digits */
+#define DSP_DIGITMODE_MF                       1                               /*!< Detect MF digits */
+
+#define DSP_DIGITMODE_NOQUELCH         (1 << 8)                /*!< Do not quelch DTMF from in-band */
+#define DSP_DIGITMODE_MUTECONF         (1 << 9)                /*!< Mute conference */
+#define DSP_DIGITMODE_MUTEMAX          (1 << 10)               /*!< Delay audio by a frame to try to extra quelch */
+#define DSP_DIGITMODE_RELAXDTMF                (1 << 11)               /*!< "Radio" mode (relaxed DTMF) */
+
+#define DSP_PROGRESS_TALK              (1 << 16)               /*!< Enable talk detection */
+#define DSP_PROGRESS_RINGING           (1 << 17)               /*!< Enable calling tone detection */
+#define DSP_PROGRESS_BUSY              (1 << 18)               /*!< Enable busy tone detection */
+#define DSP_PROGRESS_CONGESTION                (1 << 19)               /*!< Enable congestion tone detection */
 #define DSP_FEATURE_CALL_PROGRESS      (DSP_PROGRESS_TALK | DSP_PROGRESS_RINGING | DSP_PROGRESS_BUSY | DSP_PROGRESS_CONGESTION)
 
 #define DSP_TONE_STATE_SILENCE  0
index 27d1f4a..6946b54 100644 (file)
@@ -19,7 +19,8 @@
 /*!
  * \file
  * \author Russell Bryant <russell@digium.com>
- * \brief Generic event system
+ * \ref AstGenericEvents
+ * \page AstGenericEvents Generic event system
  *
  * The purpose of this API is to provide a generic way to share events between
  * Asterisk modules.  Code can generate events, and other code can subscribe to
index f0e9195..9439450 100644 (file)
  * the GNU General Public License Version 2. See the LICENSE file
  * at the top of the source tree.
  */
+/*! \file External configuration handlers (realtime and static configuration)
+ *  \author Steve Murphy <murf@digium.com>
+ *
+ */
 
 #ifndef _ASTERISK_EXTCONF_H
 #define _ASTERISK_EXTCONF_H
@@ -68,7 +72,7 @@ struct ast_config {
 
 /* ================== above: the config world; below, the dialplan world */
 
-/*! \brief ast_app: A registered application */
+/*! \brief A registered application */
 struct ast_app {
        int (*execute)(struct ast_channel *chan, void *data);
        const char *synopsis;                   /*!< Synopsis text for 'show applications' */
@@ -78,7 +82,7 @@ struct ast_app {
        char name[0];                           /*!< Name of the application */
 };
 /*!
-   \brief ast_exten: An extension
+   \brief An extension
        The dialplan is saved as a linked list with each context
        having it's own linked list of extensions - one item per
        priority.
@@ -108,7 +112,7 @@ struct ast_timing {
        unsigned int dowmask;                   /*!< Mask for day of week (mon-sun) */
        unsigned int minmask[24];               /*!< Mask for minute */
 };
-/*! \brief ast_include: include= support in extensions.conf */
+/*! \brief include= support in extensions.conf */
 struct ast_include {
        const char *name;
        const char *rname;                      /*!< Context to include */
@@ -119,7 +123,7 @@ struct ast_include {
        char stuff[0];
 };
 
-/*! \brief ast_sw: Switch statement in extensions.conf */
+/*! \brief Switch statement in extensions.conf */
 struct ast_sw {
        char *name;
        const char *registrar;                  /*!< Registrar */
@@ -130,14 +134,14 @@ struct ast_sw {
        char stuff[0];
 };
 
-*! \brief ast_ignorepat: Ignore patterns in dial plan */
+*! \brief Ignore patterns in dial plan */
 struct ast_ignorepat {
        const char *registrar;
        struct ast_ignorepat *next;
        const char pattern[0];
 };
 
-/*! \brief ast_context: An extension context */
+/*! \brief An extension context */
 struct ast_context {
        ast_rwlock_t lock;                      /*!< A lock to prevent multiple threads from clobbering the context */
        struct ast_exten *root;                 /*!< The root of the list of extensions */
index 0f8e1f9..ed9a95e 100644 (file)
@@ -21,8 +21,9 @@
 
 /*! \file
  * \brief Generic (perhaps overly so) hashtable implementation
-*/
-/*! \note
+ * \ref AstHash
+ */
+/*! \page AstHash Hash Table support in Asterisk
 
 A hash table is a structure that allows for an exact-match search
 in O(1) (or close to that) time.
@@ -39,6 +40,7 @@ The key for a value must be contained in the value, or we won't
 be able to find it in the bucket list.
 
 This implementation is pretty generic, because:
+
  1. The value and key are expected to be in a structure
     (along with other data, perhaps) and it's address is a "void *".
  2. The pointer to a compare function must be passed in at the
index 6f227dc..ee22994 100644 (file)
@@ -48,7 +48,7 @@ extern "C" {
 /*! Invalid fd */
 #define AST_IO_NVAL    POLLNVAL
 
-/*!
+/*! \brief
  * An Asterisk IO callback takes its id, a file descriptor, list of events, and
  * callback data as arguments and returns 0 if it should not be
  * run again, or non-zero if it should be run again.
index 4d46198..25dd92e 100644 (file)
 #define _ASTERISK_LOCALTIME_H
 
 struct ast_tm {
-       int tm_sec;             /* Seconds. [0-60] (1 leap second) */
-       int tm_min;             /* Minutes. [0-59] */
-       int tm_hour;            /* Hours.   [0-23] */
-       int tm_mday;            /* Day.     [1-31] */
-       int tm_mon;             /* Month.   [0-11] */
-       int tm_year;            /* Year - 1900.  */
-       int tm_wday;            /* Day of week. [0-6] */
-       int tm_yday;            /* Days in year.[0-365] */
-       int tm_isdst;           /* DST.         [-1/0/1]*/
-       long int tm_gmtoff;     /* Seconds east of UTC.  */
-       char *tm_zone;          /* Timezone abbreviation.  */
+       int tm_sec;             /*!< Seconds. [0-60] (1 leap second) */
+       int tm_min;             /*!< Minutes. [0-59] */
+       int tm_hour;            /*!< Hours.   [0-23] */
+       int tm_mday;            /*!< Day.     [1-31] */
+       int tm_mon;             /*!< Month.   [0-11] */
+       int tm_year;            /*!< Year - 1900.  */
+       int tm_wday;            /*!< Day of week. [0-6] */
+       int tm_yday;            /*!< Days in year.[0-365]       */
+       int tm_isdst;           /*!< DST.               [-1/0/1]*/
+       long int tm_gmtoff;     /*!< Seconds east of UTC.  */
+       char *tm_zone;          /*!< Timezone abbreviation.  */
        /* NOTE: do NOT reorder this final item.  The order needs to remain compatible with struct tm */
-       int tm_usec;        /* microseconds */
+       int tm_usec;        /*!< microseconds */
 };
 
 struct ast_tm *ast_localtime(const struct timeval *timep, struct ast_tm *p_tm, const char *zone);
index 8cc8d62..cc4abb9 100644 (file)
@@ -43,9 +43,8 @@ extern "C" {
 #define VERBOSE_PREFIX_3 "    -- "
 #define VERBOSE_PREFIX_4 "       > "
 
-/*! Used for sending a log message */
-/*!
-       \brief This is the standard logger function.  Probably the only way you will invoke it would be something like this:
+/*! \brief Used for sending a log message 
+       This is the standard logger function.  Probably the only way you will invoke it would be something like this:
        ast_log(LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
        where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
        on which log you wish to output to. These are implemented as macros, that
index fad3513..c51bf68 100644 (file)
@@ -31,8 +31,9 @@
 extern "C" {
 #endif
 
-/*!
- * Each supported file format is described by the following fields.
+/*! \brief
+ * Each supported file format is described by the following structure.
+ *
  * Not all are necessary, the support routine implement default
  * values for some of them.
  * A handler typically fills a structure initializing the desired
@@ -91,7 +92,7 @@ struct ast_format {
        struct ast_module *module;
 };
 
-/*!
+/*! \brief
  * This structure is allocated by file.c in one chunk,
  * together with buf_size and desc_size bytes of memory
  * to be used for private purposes (e.g. buffers etc.)