nua: updated documentation. Fixed references to headers.

darcs-hash:20070627094612-65a35-a40398f0eff6b6f258dd074f8d88d0c355b26203.gz

libsofia-sip-ua/nua/nua.c

@@ -1040,19 +1040,30 @@ void nua_event(nua_t *root_magic, su_msg_r sumsg, event_t *e)
   su_msg_destroy(nua->nua_current);
 }
 
-/** Get current request message. @NEW_1_12_4. */
+/** Get current request message. @NEW_1_12_4.
+ *
+ * @note A response message is returned when processing response message.
+ *
+ * @sa #nua_event_e, nua_respond(), NUTAG_WITH_CURRENT()
+ */
 msg_t *nua_current_request(nua_t const *nua)
 {
   return nua && nua->nua_current ? su_msg_data(nua->nua_current)->e_msg : NULL;
 }
 
-/** Get request message from saved nua event. @NEW_1_12_4. */
+/** Get request message from saved nua event. @NEW_1_12_4. 
+ *
+ * @sa nua_save_event(), nua_respond(), NUTAG_WITH_SAVED(), 
+ */
 msg_t *nua_saved_event_request(nua_saved_event_t const *saved)
 {
   return saved && saved[0] ? su_msg_data(saved)->e_msg : NULL;
 }
 
-/** Save nua event and its arguments */
+/** Save nua event and its arguments.
+ *
+ * @sa #nua_event_e, nua_event_data() nua_saved_event_request(), nua_destroy_event()
+ */
 int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1])
 {
   if (nua && return_saved) {
@@ -1066,13 +1077,19 @@ int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1])
   return 0;
 }
 
-/** Get event data */
+/** Get event data.
+ *
+ * @sa #nua_event_e, nua_event_save(), nua_saved_event_request(), nua_destroy_event().
+ */
 nua_event_data_t const *nua_event_data(nua_saved_event_t const saved[1])
 {
   return saved ? su_msg_data(saved) : NULL;
 }
 
-/** Destroy saved event */
+/** Destroy saved event.
+ *
+ * @sa #nua_event_e, nua_event_save(), nua_event_data(), nua_saved_event_request().
+ */
 void nua_destroy_event(nua_saved_event_t saved[1])
 {
   if (su_msg_is_non_null(saved)) {

libsofia-sip-ua/nua/nua.docs

@@ -26,18 +26,18 @@ The NUA API gives the high-level application programmer transparent and
 full control to the SIP protocol engine below it. NUA provides the call
 semantics on top of existing transaction semantics found in
 <a href="../nta/index.html"><b>nta</b></a> module.
-API makes it possible to create different kind of User Agents,
+With NUA it is possible to create different kind of SIP User Agents,
 like terminals, gateways or MCUs.
 
 The @b nua engine hides many low-level signaling and media management
 aspects from the application programmer. It is possible to use different
 kind of media interfaces - even remote ones - in a fully transparent way.
 
-The application and the protocol engine within User Agent library can be
-run in separate threads. Communications from the protocol engine is
-conveyed through a callback function. The callback function is called
-within context of the application, so the application must provide
-appropriate handle to a #su_root_t object.
+The application and the protocol engine within User Agent library can be run
+in separate threads. The protocol engine communicates with the application
+using @ref nua_event_e "events", delivered to the application with a a
+callback function. The callback function is called within the thread context
+of the application, represented with a #su_root_t object.
 
 @section nua_concepts_user Sofia Concepts for NUA User
 
@@ -74,14 +74,14 @@ the main event loop of the task. Through the root object the task code
 can access its context information (magic) and thread-synchronization
 features like wait objects, timers, and messages.
 
-An application using NUA services must create a root object and the
-callback routine to handle events. The root object is created with
-su_root_create() function and the callback routine is registered with
+An application using NUA services must create a root object and the callback
+routine to handle @ref nua_event_e "NUA events". The root object is created
+with su_root_create() function and the callback routine is registered with
 nua_create() function.
 
 Root object has type #su_root_t.
 
-See documentation of <su_wait.h> and <su_root.c> for more information
+See documentation of <sofia-sip/su_wait.h> and <su_root.c> for more information
 of root object.
 
 See section #nua_event_e for more information of the callback function.
@@ -109,8 +109,8 @@ separately.
 An application using NUA services can use the memory management services
 provided by the SU library but it is not mandatory.
 
-See documentation of <su_alloc.h> for more information of memory management
-services.
+See documentation of <sofia-sip/su_alloc.h> for more information of memory
+management services.
 
 @subsection nua_tags Tags
 
@@ -169,14 +169,14 @@ An application using NUA services must use tagged arguments for passing the
 parameters to functions. See nua_invite() for discussion on how a SIP
 message is constructed from the tags.
 
-See documentation of <su_tag.h> for more information of tags and the
+See documentation of <sofia-sip/su_tag.h> for more information of tags and the
 module-specific documentation of each Sofia module for information of
 tags specific for that module.
 
 @subsection nua_debugandlogging Debugging and Logging
 
 The modules of Sofia stack contain configurable debugging and logging
-functionality based on the services defined in <su_log.h>. The debugging
+functionality based on the services defined in <sofia-sip/su_log.h>. The debugging
 and logging details (for example level of details on output and output
 file name) can be configured by environment variables, directives in
 configuration files and compilation directives in the source files.
@@ -201,7 +201,7 @@ The defined debug output levels are:
 An application using NUA services can also use the debugging and
 logging services provided by the Sofia stack but it is not mandatory.
 
-See documentation of <su_log.h> for more information of debugging and
+See documentation of <sofia-sip/su_log.h> for more information of debugging and
 logging services.
 
 @section nua_concepts NUA Concepts
@@ -2089,6 +2089,8 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
  * #nua_r_unregister  \n
  * #nua_r_unsubscribe \n
  * #nua_r_update
+ * 
+ * @sa nua_event_is_incoming_request(), nua_event_name()
  */
 
 /** @NUA_EVENT nua_i_chat

libsofia-sip-ua/nua/nua_common.c

@@ -235,7 +235,7 @@ char const *nua_generate_instance_identifier(su_home_t *home)
  *   ...
  * @endcode
  *
- * @sa #nua_event_t, nua_respond()
+ * @sa nua_respond(), #nua_event_e, #nua_event_t, nua_event_name()
  *
  * @NEW_1_12_6
  */
@@ -260,7 +260,10 @@ int nua_event_is_incoming_request(nua_event_t event)
   }
 }
 
-/** Get name for a NUA event. */
+/** Get name for a NUA event. 
+ *
+ * @sa #nua_event_e, #nua_event_t, nua_callstate_name(), nua_substate_name()
+ */
 char const *nua_event_name(nua_event_t event)
 {
   switch (event) {
@@ -329,7 +332,10 @@ char const *nua_event_name(nua_event_t event)
   }
 }
 
-/** Return name of call state */
+/** Return name of call state.
+ * 
+ * @sa enum #nua_callstate, nua_event_name(), nua_substate_name()
+ */
 char const *nua_callstate_name(enum nua_callstate state)
 {
   switch (state) {
@@ -348,7 +354,10 @@ char const *nua_callstate_name(enum nua_callstate state)
   }
 }
 
-/** Return name of subscription state. @NEW_1_12_5. */
+/** Return name of subscription state. @NEW_1_12_5. 
+ *
+ * @sa enum #nua_substate, nua_event_name(), nua_callstate_name()
+ */
 char const *nua_substate_name(enum nua_substate substate)
 {
   switch (substate) {

libsofia-sip-ua/nua/nua_extension.c

@@ -63,7 +63,7 @@
  *    NUTAG_METHOD() \n
  *    NUTAG_URL() \n
  *    Tags of nua_set_hparams() \n
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_method

libsofia-sip-ua/nua/nua_message.c

@@ -64,7 +64,7 @@
  * @par Related Tags:
  *    NUTAG_URL() \n
  *    Tags of nua_set_hparams() \n
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_message

libsofia-sip-ua/nua/nua_notifier.c

@@ -366,7 +366,7 @@ int nua_subscribe_server_report(nua_server_request_t *sr, tagi_t const *tags)
  * @par Related Tags:
  *    NUTAG_SUBSTATE() \n
  *    Tags of nua_set_hparams() \n
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_notify

libsofia-sip-ua/nua/nua_options.c

@@ -58,7 +58,7 @@
  *    nothing
  *
  * @par Related Tags:
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_options

libsofia-sip-ua/nua/nua_publish.c

@@ -138,7 +138,7 @@ void nua_publish_usage_remove(nua_handle_t *nh,
  * @par Related Tags:
  *    NUTAG_URL() \n
  *    Tags of nua_set_hparams() \n
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_publish
@@ -196,7 +196,7 @@ void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
  *    SIPTAG_IF_MATCH(), SIPTAG_IF_MATCH_STR() \n
  *    SIPTAG_EVENT(), SIPTAG_EVENT_STR() \n
  *    Tags of nua_set_hparams() \n
- *    Tags in <sip_tag.h>
+ *    Other header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
  *
  * @par Events:
  *    #nua_r_unpublish

libsofia-sip-ua/nua/nua_register.c

@@ -516,7 +516,7 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
  *
  * @par Related tags:
  *     NUTAG_REGISTRAR() \n
- *     Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
+ *     Header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
  *
  * @par Events:
  *     #nua_r_unregister

libsofia-sip-ua/nua/nua_session.c

@@ -999,7 +999,7 @@ static int nua_invite_client_report(nua_client_request_t *cr,
  *    nothing
  *
  * @par Related Tags:
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_i_media_error \n
@@ -1217,7 +1217,7 @@ static int nua_invite_client_deinit(nua_client_request_t *cr)
  *    nothing
  *
  * @par Related Tags:
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_cancel, #nua_i_state  (#nua_i_active, #nua_i_terminated)
@@ -2714,7 +2714,7 @@ nh_referral_respond(nua_handle_t *nh, int status, char const *phrase)
  *    nothing
  *
  * @par Related Tags:
- *    Tags in <sip_tag.h>.
+ *    Header tags defined in <sofia-sip/sip_tag.h>.
  *
  * @par Events:
  *    #nua_r_info

libsofia-sip-ua/nua/nua_stack.c

@@ -1336,7 +1336,7 @@ void nua_server_request_destroy(nua_server_request_t *sr)
  *    SOATAG_AF() \n
  *    SOATAG_HOLD() \n
  *    Tags used with nua_set_hparams() \n
- *    Tags in <sip_tag.h>.
+ *    Header tags defined in <sofia-sip/sip_tag.h>.
  *
  * @par Events:
  *    #nua_i_state \n

libsofia-sip-ua/nua/nua_subnotref.c

@@ -138,7 +138,7 @@ void nua_subscribe_usage_remove(nua_handle_t *nh,
  *
  * @par Related Tags:
  *    NUTAG_URL()
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_subscribe \n
@@ -164,7 +164,7 @@ void nua_subscribe_usage_remove(nua_handle_t *nh,
  *
  * @par Related Tags:
  *    SIPTAG_EVENT() or SIPTAG_EVENT_STR() \n
- *    Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
+ *    Header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
  *
  * @par Events:
  *    #nua_r_unsubscribe 
@@ -727,7 +727,7 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags)
  * @par Related Tags:
  *    NUTAG_URL() \n
  *    Tags of nua_set_hparams() \n
- *    Tags in <sip_tag.h>
+ *    Header tags defined in <sofia-sip/sip_tag.h>
  *
  * @par Events:
  *    #nua_r_refer \n

libsofia-sip-ua/nua/sofia-sip/nua.h

@@ -172,6 +172,7 @@ typedef struct event_s {
 /** NUA module version */
 SOFIAPUBVAR char const nua_version[];
 
+/** Typedef of NUA event callback. */
 typedef void (*nua_callback_f)(nua_event_t event,
 			       int status, char const *phrase,
 			       nua_t *nua, nua_magic_t *magic,
@@ -349,9 +350,10 @@ SOFIAPUBFUN void nua_respond(nua_handle_t *nh,
 /** Check if event can be responded with nua_respond() */
 SOFIAPUBFUN int nua_event_is_incoming_request(nua_event_t e);
 
+/** Cast a #nua_handle_t pointer to a #su_home_t. */
 #define nua_handle_home(nh) ((su_home_t *)(nh))
 
-/** Generate an instance identifier */
+/** Generate an instance identifier. */
 SOFIAPUBFUN char const *nua_generate_instance_identifier(su_home_t *);
 
 #ifndef NUA_SAVED_EVENT_T