sip: codestyle changes

Shuffle the code around and make use of docstrings to conform to
the newly introduced coding style as described in `HACKING.md`

This commit also introduces docstrings describing each source file.

plugins/sip/calls-sip-call.c

@@ -24,17 +24,34 @@
 
 #define G_LOG_DOMAIN "CallsSipCall"
 
-#include "calls-sip-call.h"
 
+#include "calls-call.h"
 #include "calls-message-source.h"
+#include "calls-sip-call.h"
 #include "calls-sip-media-manager.h"
 #include "calls-sip-media-pipeline.h"
 #include "calls-sip-util.h"
-#include "calls-call.h"
 
 #include <glib/gi18n.h>
+
 #include <sofia-sip/nua.h>
 
+/**
+ * SECTION:sip-call
+ * @short_description: A #CallsCall for the SIP protocol
+ * @Title: CallsSipCall
+ *
+ * #CallsSipCall derives from #CallsCall. Apart from allowing call control
+ * like answering and hanging up it also coordinates with #CallsSipMediaManager
+ * to prepare and control appropriate #CallsSipMediaPipeline objects.
+ */
+
+enum {
+  PROP_0,
+  PROP_CALL_HANDLE,
+  PROP_LAST_PROP
+};
+static GParamSpec *props[PROP_LAST_PROP];
 
 struct _CallsSipCall
 {
@@ -62,14 +79,6 @@ G_DEFINE_TYPE_WITH_CODE (CallsSipCall, calls_sip_call, CALLS_TYPE_CALL,
                          G_IMPLEMENT_INTERFACE (CALLS_TYPE_MESSAGE_SOURCE,
                                                 calls_sip_call_message_source_interface_init))
 
-enum {
-  PROP_0,
-  PROP_CALL_HANDLE,
-  PROP_LAST_PROP
-};
-static GParamSpec *props[PROP_LAST_PROP];
-
-
 static gboolean
 try_setting_up_media_pipeline (CallsSipCall *self)
 {
@@ -115,6 +124,7 @@ calls_sip_call_get_number (CallsCall *call)
   return self->number;
 }
 
+
 static CallsCallState
 calls_sip_call_get_state (CallsCall *call)
 {
@@ -123,6 +133,7 @@ calls_sip_call_get_state (CallsCall *call)
   return self->state;
 }
 
+
 static gboolean
 calls_sip_call_get_inbound (CallsCall *call)
 {
@@ -131,6 +142,7 @@ calls_sip_call_get_inbound (CallsCall *call)
   return self->inbound;
 }
 
+
 static void
 calls_sip_call_answer (CallsCall *call)
 {
@@ -169,6 +181,7 @@ calls_sip_call_answer (CallsCall *call)
   calls_sip_call_set_state (self, CALLS_CALL_STATE_ACTIVE);
 }
 
+
 static void
 calls_sip_call_hang_up (CallsCall *call)
 {
@@ -205,6 +218,7 @@ calls_sip_call_hang_up (CallsCall *call)
   }
 }
 
+
 static void
 calls_sip_call_set_property (GObject      *object,
                              guint         property_id,
@@ -287,6 +301,7 @@ calls_sip_call_class_init (CallsSipCallClass *klass)
   g_object_class_install_property (object_class, PROP_CALL_HANDLE, props[PROP_CALL_HANDLE]);
 }
 
+
 static void
 calls_sip_call_message_source_interface_init (CallsMessageSourceInterface *iface)
 {

plugins/sip/calls-sip-media-manager.c

@@ -24,12 +24,21 @@
 
 #define G_LOG_DOMAIN "CallsSipMediaManager"
 
-#include "calls-sip-media-pipeline.h"
-#include "gst-rfc3551.h"
 #include "calls-sip-media-manager.h"
+#include "gst-rfc3551.h"
 
 #include <gst/gst.h>
 
+/**
+ * SECTION:sip-media-manager
+ * @short_description: The media manager singleton
+ * @Title: CallsSipMediaManager
+ *
+ * #CallsSipMediaManager is mainly responsible for generating appropriate
+ * SDP messages for the set of supported codecs. In the future it
+ * shall also manage the #CallsSipMediaPipeline objects that are in use.
+ */
+
 typedef struct _CallsSipMediaManager
 {
   GObject parent;

plugins/sip/calls-sip-media-pipeline.c

@@ -29,6 +29,35 @@
 #include <gst/gst.h>
 #include <gio/gio.h>
 
+/**
+ * SECTION:sip-media-pipeline
+ * @short_description:
+ * @Title:
+ *
+ * #CallsSipMediaPipeline is responsible for building Gstreamer pipelines.
+ * Usually a sender and receiver pipeline is employed.
+ *
+ * The sender pipeline records audio and uses RTP to send it out over the network
+ * to the specified host.
+ * The receiver pipeline receives RTP from the network and plays the audio
+ * on the system.
+ *
+ * Both pipelines are using RTCP.
+ */
+
+enum {
+  PROP_0,
+  PROP_CODEC,
+  PROP_REMOTE,
+  PROP_LPORT_RTP,
+  PROP_RPORT_RTP,
+  PROP_LPORT_RTCP,
+  PROP_RPORT_RTCP,
+  PROP_DEBUG,
+  PROP_LAST_PROP,
+};
+static GParamSpec *props[PROP_LAST_PROP];
+
 struct _CallsSipMediaPipeline {
   GObject parent;
 
@@ -78,23 +107,9 @@ static void initable_iface_init (GInitableIface *iface);
 G_DEFINE_TYPE_WITH_CODE (CallsSipMediaPipeline, calls_sip_media_pipeline, G_TYPE_OBJECT,
                          G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE, initable_iface_init));
 
-enum {
-  PROP_0,
-  PROP_CODEC,
-  PROP_REMOTE,
-  PROP_LPORT_RTP,
-  PROP_RPORT_RTP,
-  PROP_LPORT_RTCP,
-  PROP_RPORT_RTCP,
-  PROP_DEBUG,
-  PROP_LAST_PROP,
-};
-static GParamSpec *props[PROP_LAST_PROP];
-
-
 /* rtpbin adds a pad once the payload is verified */
 static void
-pad_added_cb (GstElement *rtpbin,
+on_pad_added (GstElement *rtpbin,
               GstPad     *srcpad,
               GstElement *depayloader)
 {
@@ -113,7 +128,7 @@ pad_added_cb (GstElement *rtpbin,
 
 
 static gboolean
-bus_cb (GstBus *bus,
+on_bus_message (GstBus     *bus,
                 GstMessage *message,
                 gpointer    data)
 {
@@ -426,8 +441,8 @@ initable_init (GInitable    *initable,
 /* get the busses and establish watches */
   self->bus_send = gst_pipeline_get_bus (GST_PIPELINE (self->send_pipeline));
   self->bus_recv = gst_pipeline_get_bus (GST_PIPELINE (self->recv_pipeline));
-  self->bus_watch_send = gst_bus_add_watch (self->bus_send, bus_cb, self);
+  self->bus_watch_send = gst_bus_add_watch (self->bus_send, on_bus_message, self);
-  self->bus_watch_recv = gst_bus_add_watch (self->bus_recv, bus_cb, self);
+  self->bus_watch_recv = gst_bus_add_watch (self->bus_recv, on_bus_message, self);
 
   gst_bin_add_many (GST_BIN (self->recv_pipeline), self->depayloader, self->decoder,
                     self->audiosink, NULL);
@@ -568,7 +583,7 @@ initable_init (GInitable    *initable,
   gst_object_unref (sinkpad);
 
   /* need to link RTP pad to the depayloader */
-  g_signal_connect (self->recv_rtpbin, "pad-added", G_CALLBACK (pad_added_cb), self->depayloader);
+  g_signal_connect (self->recv_rtpbin, "pad-added", G_CALLBACK (on_pad_added), self->depayloader);
 
 
   /* out/send direction */

plugins/sip/calls-sip-origin.c

@@ -24,24 +24,53 @@
 
 #define G_LOG_DOMAIN "CallsSipOrigin"
 
-#include "config.h"
-#include "calls-sip-origin.h"
 
 #include "calls-message-source.h"
 #include "calls-origin.h"
 #include "calls-sip-call.h"
-#include "calls-sip-util.h"
 #include "calls-sip-enums.h"
+#include "calls-sip-origin.h"
+#include "calls-sip-util.h"
 #include "calls-sip-media-manager.h"
+#include "config.h"
 
 #include <glib/gi18n.h>
 #include <glib-object.h>
+
 #include <sofia-sip/nua.h>
 #include <sofia-sip/su_tag.h>
 #include <sofia-sip/su_tag_io.h>
 #include <sofia-sip/sip_util.h>
 #include <sofia-sip/sdp.h>
 
+/**
+ * SECTION:sip-origin
+ * @short_description: A #CallsOrigin for the SIP protocol
+ * @Title: CallsSipOrigin
+ *
+ * #CallsSipOrigin implements the #CallsOriginInterface and is mainly
+ * responsible for managing the sofia-sip callbacks, keeping track of #CallsSipCall
+ * objects and coordinating with #CallsSipMediaManager.
+ */
+
+enum {
+  PROP_0,
+  PROP_NAME,
+  PROP_ACC_USER,
+  PROP_ACC_PASSWORD,
+  PROP_ACC_HOST,
+  PROP_ACC_PORT,
+  PROP_ACC_PROTOCOL,
+  PROP_ACC_DIRECT,
+  PROP_ACC_AUTO_CONNECT,
+  PROP_SIP_CONTEXT,
+  PROP_SIP_LOCAL_PORT,
+  PROP_ACC_STATE,
+  PROP_CALLS,
+  PROP_COUNTRY_CODE,
+  PROP_LAST_PROP,
+};
+static GParamSpec *props[PROP_LAST_PROP];
 
 struct _CallsSipOrigin
 {
@@ -90,26 +119,6 @@ G_DEFINE_TYPE_WITH_CODE (CallsSipOrigin, calls_sip_origin, G_TYPE_OBJECT,
                          G_IMPLEMENT_INTERFACE (CALLS_TYPE_ORIGIN,
                                                 calls_sip_origin_origin_interface_init))
 
-enum {
-  PROP_0,
-  PROP_NAME,
-  PROP_ACC_USER,
-  PROP_ACC_PASSWORD,
-  PROP_ACC_HOST,
-  PROP_ACC_PORT,
-  PROP_ACC_PROTOCOL,
-  PROP_ACC_DIRECT,
-  PROP_ACC_AUTO_CONNECT,
-  PROP_SIP_CONTEXT,
-  PROP_SIP_LOCAL_PORT,
-  PROP_ACC_STATE,
-  PROP_CALLS,
-  PROP_COUNTRY_CODE,
-  PROP_LAST_PROP,
-};
-static GParamSpec *props[PROP_LAST_PROP];
-
-
 static void
 remove_call (CallsSipOrigin *self,
              CallsCall      *call,
@@ -166,7 +175,7 @@ remove_calls (CallsSipOrigin *self,
 
 
 static void
-on_call_state_changed_cb (CallsSipOrigin *self,
+on_call_state_changed (CallsSipOrigin *self,
                        CallsCallState  new_state,
                        CallsCallState  old_state,
                        CallsCall      *call)
@@ -211,7 +220,7 @@ add_call (CallsSipOrigin *self,
 
   g_signal_emit_by_name (CALLS_ORIGIN (self), "call-added", call);
   g_signal_connect_swapped (call, "state-changed",
-                            G_CALLBACK (on_call_state_changed_cb),
+                            G_CALLBACK (on_call_state_changed),
                             self);
 
   if (!inbound) {
@@ -1166,7 +1175,7 @@ calls_sip_origin_new (const gchar     *name,
 
 /* calls_sip_origin_go_online:
  * @self: A #CallsSipOrigin
- * @enabled: Whether to go online or offline
+ * @enabled: %TRUE to go online, %FALSE to go offline
  */
 void
 calls_sip_origin_go_online (CallsSipOrigin *self,

plugins/sip/calls-sip-provider.c

@@ -24,23 +24,35 @@
 
 #define G_LOG_DOMAIN "CallsSipProvider"
 
-#define SU_ROOT_MAGIC_T CallsSipProvider
+#define SIP_ACCOUNT_FILE "sip-account.cfg"
-
-#include "calls-sip-provider.h"
 
 #include "calls-message-source.h"
 #include "calls-provider.h"
-#include "calls-sip-origin.h"
-#include "calls-sip-util.h"
 #include "calls-sip-enums.h"
+#include "calls-sip-origin.h"
+#include "calls-sip-provider.h"
+#include "calls-sip-util.h"
 #include "config.h"
 
 #include <libpeas/peas.h>
 #include <sofia-sip/nua.h>
 #include <sofia-sip/su_glib.h>
 
+/**
+ * SECTION:sip-provider
+ * @short_description: A #CallsProvider for the SIP protocol
+ * @Title: CallsSipProvider
+ *
+ * #CallsSipProvider is derived from #CallsProvider and is responsible
+ * for setting up the sofia-sip stack.
+ */
 
-#define SIP_ACCOUNT_FILE "sip-account.cfg"
+enum {
+  PROP_0,
+  PROP_SIP_STATE,
+  PROP_LAST_PROP,
+};
+static GParamSpec *props[PROP_LAST_PROP];
 
 struct _CallsSipProvider
 {
@@ -54,13 +66,6 @@ struct _CallsSipProvider
   gchar *filename;
 };
 
-enum {
-  PROP_0,
-  PROP_SIP_STATE,
-  PROP_LAST_PROP,
-};
-static GParamSpec *props[PROP_LAST_PROP];
-
 static void calls_sip_provider_message_source_interface_init (CallsMessageSourceInterface *iface);
 
 
@@ -339,6 +344,12 @@ calls_sip_provider_dispose (GObject *object)
 }
 
 
+static void
+calls_sip_provider_class_finalize (CallsSipProviderClass *klass)
+{
+}
+
+
 static void
 calls_sip_provider_class_init (CallsSipProviderClass *klass)
 {
@@ -430,12 +441,6 @@ calls_sip_provider_new ()
 }
 
 
-static void
-calls_sip_provider_class_finalize (CallsSipProviderClass *klass)
-{
-}
-
-
 G_MODULE_EXPORT void
 peas_register_types (PeasObjectModule *module)
 {