Doxygen doc

.gitignore

@@ -15,8 +15,8 @@ Makefile.in
 # Ignore rendered docs
 doc/doxygen/html-everything
 doc/doxygen/html-sflphoned
-doc/doxygen/html-gui-qt
 doc/*.html
+sflphone-gtk/doc/html/*
 
 # Ignore buildsys stuff
 /autom4te.cache

sflphone-gtk/src/accountlist.h

@@ -21,6 +21,9 @@
 #define __ACCOUNTLIST_H__
 
 #include <gtk/gtk.h>
+/** @file accountlist.h
+  * @brief A list to hold accounts.
+  */
 
 #define ACCOUNT_TYPE               "Account.type"
 #define ACCOUNT_ALIAS              "Account.alias"
@@ -39,6 +42,9 @@
 #define ACCOUNT_IAX_USER           "IAX.user"
 #define ACCOUNT_IAX_PASS           "IAX.pass"
 
+/** @enum account_state_t 
+  * This enum have all the states an account can take.
+  */
 typedef enum
 {
    ACCOUNT_STATE_INVALID = 0,
@@ -46,27 +52,50 @@ typedef enum
    ACCOUNT_STATE_UNREGISTERED   
 } account_state_t;
 
-
+/** @struct account_t
+  * @brief Account information.
+  * This struct holds information about an account.  All values are stored in the 
+  * properties GHashTable except the accountID and state.  This match how the 
+  * server internally works and the dbus API to save and retrieve the accounts details.
+  * 
+  * To retrieve the Alias for example, use g_hash_table_lookup(a->properties, ACCOUNT_ALIAS).  
+  */
 typedef struct  {
   gchar * accountID;
-  account_state_t state;
-  GHashTable * properties;
+  account_state_t state;  GHashTable * properties;
 } account_t;
 
+/** This function initialize the account list. */
 void account_list_init ();
 
+/** This function empty and free the account list. */
 void account_list_clean ();
 
+/** This function append an account to list. 
+  * @param a The account you want to add */
 void account_list_add (account_t * a);
 
+/** This function remove an account from list. 
+  * @param accountID The accountID of the account you want to remove
+  */
 void account_list_remove (const gchar * accountID);
 
-/** Return the first account that corresponds to the state */
+/** Return the first account that corresponds to the state 
+  * @param s The state
+  * @return An account or NULL */
 account_t * account_list_get_by_state ( account_state_t state);
 
+/** Return the number of accounts in the list
+  * @return The number of accounts in the list */
 guint account_list_get_size ( );
 
+/** Return the account at the nth position in the list
+  * @param n The position of the account you want
+  * @return An account or NULL */
 account_t * account_list_get_nth ( guint n );
 
+/** This function maps account_state_t enums to a description.
+  * @param s The state
+  * @return The full text description of the state */
 const gchar * account_state_name(account_state_t s);
 #endif 

sflphone-gtk/src/accountwindow.h

@@ -19,8 +19,10 @@
  
 #ifndef __ACCOUNTWINDOW_H__
 #define __ACCOUNTWINDOW_H__
+/** @file accountwindow.h
+  * @brief The window to edit account details.
+  */
   
 void show_account_window ( account_t * a );
 
-
 #endif 

sflphone-gtk/src/actions.c

@@ -29,9 +29,7 @@
 #include <dbus.h>
 #include <accountlist.h>
 
-/**
- * Terminate the gtk program
- */
+
 gboolean
 sflphone_quit ()
 {
@@ -53,9 +51,7 @@ sflphone_quit ()
   return quit;
 }
 
-/**
- * Put the line on hold
- */
+
 void 
 sflphone_hold(call_t * c )
 {
@@ -64,9 +60,6 @@ sflphone_hold(call_t * c )
   screen_clear();
 }
 
-/**
- * Put the call in Ringing state
- */
 void 
 sflphone_ringing(call_t * c )
 {
@@ -75,7 +68,7 @@ sflphone_ringing(call_t * c )
 }
 
 
-/* Fill account list */
+/** Internal to actions: Fill account list */
 void
 sflphone_fill_account_list()
 {
@@ -131,20 +124,6 @@ sflphone_init()
   }
 }
 
-/**
- * Put the line on hold
- */
-void 
-sflphone_unhold(call_t * c )
-{
-  c->state = CALL_STATE_CURRENT;
-  update_call_tree(c);
-  screen_set_call(c);
-}
-
-/**
- * Hang up the line
- */
 void 
 sflphone_hang_up( call_t  * c )
 {
@@ -153,9 +132,6 @@ sflphone_hang_up( call_t  * c )
   screen_clear();
 }
 
-/**
- * Incoming call
- */
 void 
 sflphone_current( call_t * c )
 {
@@ -164,9 +140,6 @@ sflphone_current( call_t * c )
   screen_set_call(c);
 }
 
-/**
- * Transfert the line
- */
 void 
 sflphone_transfert( call_t * c, gchar * to )
 {
@@ -174,18 +147,13 @@ sflphone_transfert( call_t * c, gchar * to )
   update_call_tree_remove(c);
 }
 
-/**
- * Signal Incoming Call
- */
 void
 sflphone_incoming_call (call_t * c) 
 {
   call_list_add ( c );
   update_call_tree_add(c);
 }
-/**
- * Signal Hung up
- */
+
 void 
 sflphone_hung_up (call_t * c )
 {
@@ -317,10 +285,4 @@ sflphone_place_call ( call_t * c )
   }
 }
 
-void 
-sflphone_remove_account ( account_t * a )
-{
-  dbus_remove_account (a->accountID);
-}
-
 

sflphone-gtk/src/actions.h

@@ -23,6 +23,13 @@
 #include <calllist.h>
 #include <accountlist.h>
 
+/** @file actions.h
+  * @brief General functions that change the state of the application.
+  * All of these functions are called when dbus signals are triggered.  Exceptions
+  * are sflphone_init() sflphone_quit(), sflphone_keypad() and sflphone_place_call().
+  */
+
+
 /**
  * Initialize lists and configurations 
  * @return TRUE if succeeded, FALSE otherwise
@@ -35,36 +42,52 @@ gboolean sflphone_init ( ) ;
  */
 gboolean sflphone_quit ( ) ;
 
+/**
+ * Hang up the call
+ */
 void sflphone_hang_up ( call_t * c);
 
+/**
+ * Transfert the call
+ */
 void sflphone_transfert ( call_t * c, gchar * to );
 
+/**
+ * Put the call on hold
+ */
 void sflphone_hold ( call_t * c);
 
+/**
+ * Put the call in Ringing state
+ */
 void sflphone_ringing(call_t * c );
 
+/**
+ * Put the call in Current state
+ */
 void sflphone_current ( call_t * c);
 
-void sflphone_remove_account ( account_t * a );
-
-void sflphone_unhold ( call_t * c);
-
-/* signals */
+/**
+ * The callee has hung up
+ */
 void sflphone_hung_up( call_t * c);
 
-/* void sflphone_ring */
+/**
+ * Incoming call
+ */
 void sflphone_incoming_call ( call_t * c);
 
 /**
  * Dial the number
  * If the call is in DIALING state, the char will be append to the number
- * TODO If the call is in CURRENT state, the char will be also sent to the server 
- * @param c A call in CALL_STATE_DIALING state
+ * @TODO If the call is in CURRENT state, the char will be also sent to the server 
+ * @param keyval The unique int representing the key
+ * @param keyval The char value of the key
  */
 void sflphone_keypad ( guint keyval, gchar * key);
 
 /**
- * Place a call
+ * Place a call with a filled call_t.to 
  * @param c A call in CALL_STATE_DIALING state
  */
 void sflphone_place_call ( call_t * c );

sflphone-gtk/src/calllist.h

@@ -21,42 +21,90 @@
 #define __CALLLIST_H__
 
 #include <gtk/gtk.h>
+/** @file calllist.h
+  * @brief A list to hold calls.
+  */
   
+/** @enum call_state_t 
+  * This enum have all the states a call can take.
+  */
 typedef enum
-{
+{  /** Invalid state */
    CALL_STATE_INVALID = 0, 
-   CALL_STATE_INCOMING, /* Ringing incoming call */
-   CALL_STATE_RINGING,  /* Ringing outgoing call */
+   /** Ringing incoming call */
+   CALL_STATE_INCOMING, 
+   /** Ringing outgoing call */
+   CALL_STATE_RINGING,  
+   /** Call to which the user can speak and hear */
    CALL_STATE_CURRENT,  
+   /** Call which numbers are being added by the user */
    CALL_STATE_DIALING,  
+   /** Call is on hold */
    CALL_STATE_HOLD      
 } call_state_t;
 
+
+/** @struct call_t
+  * @brief Call information.
+  * This struct holds information about a call.    
+  */
 typedef struct  {
+  /** Unique identifier of the call */
   gchar * callID;
+  /** The account used to place/receive the call */
   gchar * accountID;
+  /** The information about the calling person.  See call_get_name() and call_get_number()
+    * on how to get the name and number separately. */
   gchar * from;
+  /** The number we are calling.  Only used when dialing out */
   gchar * to;
+  /* The current state of the call */
   call_state_t state;
 } call_t;
 
+/** This function initialize the call list. */
 void call_list_init ();
 
+/** This function empty and free the call list. */
 void call_list_clean ();
 
+/** This function append a call to list. 
+  * @param c The call you want to add */
 void call_list_add (call_t * c);
 
+/** This function remove a call from list. 
+  * @param callID The callID of the call you want to remove
+  */
 void call_list_remove (const gchar * callID);
 
+/** Return the first call that corresponds to the state.  
+  * This is usefull for unique states as DIALING and CURRENT.
+  * @param state The state
+  * @return A call or NULL */
 call_t * call_list_get_by_state ( call_state_t state);
 
+/** Return the number of calls in the list
+  * @return The number of calls in the list */
 guint call_list_get_size ( );
 
+/** Return the call at the nth position in the list
+  * @param n The position of the call you want
+  * @return A call or NULL */
 call_t * call_list_get_nth ( guint n );
+
+/** Return the call corresponding to the callID
+  * @param n The callID of the call you want
+  * @return A call or NULL */
 call_t * call_list_get ( const gchar * callID );
 
+/** This function parse the call_t.from field to return the name
+  * @param c The call
+  * @return The full name of the caller or an empty string */
 gchar * call_get_name (const call_t * c);
 
+/** This function parse the call_t.from field to return the number
+  * @param c The call
+  * @return The number of the caller */
 gchar * call_get_number (const call_t * c);
 
 #endif 

sflphone-gtk/src/calltree.h

@@ -23,6 +23,9 @@
 #include <gtk/gtk.h>
 #include <calllist.h>
 
+/** @file calltree.h
+  * @brief The GtkTreeView that list calls in the main window.
+  */
 GtkWidget * create_call_tree();
 
 void update_call_tree_add (call_t * c);

sflphone-gtk/src/configwindow.c

@@ -17,11 +17,12 @@
  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
  
-#include <config.h>
-#include <mainwindow.h>
 #include <accountlist.h>
 #include <accountwindow.h>
 #include <actions.h>
+#include <config.h>
+#include <dbus.h>
+#include <mainwindow.h>
 
 #include <gtk/gtk.h>
 
@@ -56,7 +57,6 @@ fill_account_list ()
   				   -1);
 
   	}
-    
   } 
   
   gtk_widget_set_sensitive( GTK_WIDGET(editButton),   FALSE);
@@ -70,7 +70,7 @@ delete_account( GtkWidget *widget, gpointer   data )
 {
   if(selectedAccount)
   {
-    sflphone_remove_account(selectedAccount);
+    dbus_remove_account(selectedAccount->accountID);
     fill_account_list ();
   }
 }
@@ -146,7 +146,7 @@ create_accounts_tab()
 	gtk_widget_show(label);
 
 	sw = gtk_scrolled_window_new(NULL,NULL);
-	gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(sw), GTK_POLICY_AUTOMATIC, GTK_POLICY_ALWAYS);
+	gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(sw), GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC);
 	gtk_scrolled_window_set_shadow_type(GTK_SCROLLED_WINDOW(sw), GTK_SHADOW_IN);
 
 	gtk_box_pack_start(GTK_BOX(ret), sw, TRUE, TRUE, 0);

sflphone-gtk/src/configwindow.h

@@ -22,7 +22,9 @@
 
 #include <calllist.h>
 
-
+/** @file configwindow.h
+  * @brief The Preferences window.
+  */
 void show_config_window ( );
 
 

sflphone-gtk/src/dbus.c

@@ -100,10 +100,6 @@ call_state_cb (DBusGProxy *proxy,
     {
       sflphone_hold (c);
     }
-    else if ( strcmp(state, "UNHOLD") == 0 )
-    {
-      sflphone_unhold (c);
-    }
     else if ( strcmp(state, "RINGING") == 0 )
     {
       sflphone_ringing (c);

sflphone-gtk/src/dbus.h

@@ -24,6 +24,9 @@
 #include <accountlist.h>
 #include <calllist.h>
 
+/** @file dbus.h
+  * @brief General DBus functions wrappers.
+  */
 /** @return TRUE if connection succeeded, FALSE otherwise */
 gboolean dbus_connect ();
 void dbus_clean ();

sflphone-gtk/src/dialpad.h

@@ -21,7 +21,9 @@
 #define __DIALPAD_H__
 
 #include <gtk/gtk.h>
-
+/** @file dialpad.h
+  * @brief The dialpad widgets.
+  */
 GtkWidget * create_dialpad();
 
 #endif 

sflphone-gtk/src/main.c

@@ -25,8 +25,6 @@
 
 #include <gtk/gtk.h>
 
-
-
 int
 main (int argc, char *argv[])
 {
@@ -48,3 +46,57 @@ There is NO WARRANTY, to the extent permitted by law.\n\n");
   return 0;
 }
 
+/** @mainpage SFLphone GTK+ Client Documentation 
+  * SFLphone GTK+ Client was started as a debuging tool for the new dbus API but
+  * ended being a full featured client.  
+  * @section intro_sec Architecture
+  * SFLphone respects the MVC principle.  Since the internal workings and the UI 
+  * are too different programs, dbus is used to exchange data between them.  Dbus
+  * is thereby inforcing MVC by only allowing access to high level functions and data.
+  *
+  * Therefore, when a button is clicked, a direct dbus API call should happen 
+  * (defined in dbus.h).  The UI should only be updated when signals are received 
+  * from dbus.  The call back to those signals are defined in dbus.c, but they call
+  * functions in actions.h.  This makes things cleaner as one signal could have many 
+  * actions.
+  *
+  * Accounts are stored in form of a account_t in an account list with access functions
+  * defined in accountlist.h.
+  *
+  * Calls are stored in form of a call_t in a call list with access functions defined
+  * in calllist.h.
+  *
+  */
+
+// This doc is for generated files that get overridden by tools.  
+/** @file marshaller.h
+  * @brief This file contains marshallers functions for dbus signals.
+  * This file is generated by glib-genmarshall. 
+  * Every dbus signal has to have a marshaller.  To generate a new marshaller function, 
+  * add its signature to the marshaller.list.  Then run :
+  * <pre>glib-genmarshal --body --g-fatal-warnings marshaller.list > marshaller.c
+  *glib-genmarshal --header --g-fatal-warnings marshaller.list > marshaller.h </pre>
+  *
+  * to get the generated marshallers.
+  * Just before connecting to the dbus signal, register the marshaller with: 
+  * dbus_g_object_register_marshaller().
+  */
+  
+/** @file callmanager-glue.h
+  * @brief CallManager dbus API.
+  * This file is generated by dbus-binding-tool using the server's 
+  * callmanager-introspec.xml.  
+  * 
+  * This file dbus calls wrapper functions to simplify access to dbus API. 
+  * 
+  */
+  
+
+/** @file configurationmanager-glue.h
+  * @brief ConfigurationManager dbus API.
+  * This file is generated by dbus-binding-tool using the server's 
+  * configurationmanager-introspec.xml.  
+  * 
+  * This file dbus calls wrapper functions to simplify access to dbus API. 
+  * 
+  */

sflphone-gtk/src/mainwindow.h

@@ -22,6 +22,9 @@
 
 #include <calllist.h>
 
+/** @file mainwindow.h
+  * @brief The main window of the client.
+  */
 GtkAccelGroup * get_accel_group();
 GtkWidget * get_main_window();
 

sflphone-gtk/src/menus.h

@@ -21,7 +21,9 @@
 #define __MENUS_H__
 
 #include <gtk/gtk.h>
-
+/** @file menus.h
+  * @brief The menus of the main window.
+  */
 GtkWidget * create_menus();
 
 #endif 

sflphone-gtk/src/screen.h

@@ -23,6 +23,9 @@
 #include <gtk/gtk.h>
 #include <calllist.h>
 
+/** @file screen.h
+  * @brief The screen at the top of the main window.
+  */
 GtkWidget * create_screen();
 
 void screen_clear();

sflphone-gtk/src/sliders.h

@@ -21,7 +21,9 @@
 #define __SLIDERS_H__
 
 #include <gtk/gtk.h>
-
+/** @file sliders.h
+  * @brief Volume sliders at the bottom of the main window.
+  */
 GtkWidget * create_mic_slider();
 
 GtkWidget * create_slider(const gchar * device);