[farsight2/master] Document the FsRtpSpecialSource class

[Olivier Crête]

---
 gst/fsrtpconference/fs-rtp-discover-codecs.h |    7 ++++
 gst/fsrtpconference/fs-rtp-special-source.c  |   39 ++++++++++++++++++++++++++
 gst/fsrtpconference/fs-rtp-special-source.h  |   22 ++++++++++++++-
 3 files changed, 67 insertions(+), 1 deletions(-)

diff --git a/gst/fsrtpconference/fs-rtp-discover-codecs.h b/gst/fsrtpconference/fs-rtp-discover-codecs.h
index c013ccc..ba7b95b 100644
--- a/gst/fsrtpconference/fs-rtp-discover-codecs.h
+++ b/gst/fsrtpconference/fs-rtp-discover-codecs.h
@@ -31,6 +31,13 @@
 
 G_BEGIN_DECLS
 
+/**
+ * CodecBlueprint:
+ *
+ * All the members MUST be filled, except for send_pipeline_factory in the
+ * case of a #FsRtpSpecialSource
+ */
+
 typedef struct _CodecBlueprint
 {
   FsCodec *codec;
diff --git a/gst/fsrtpconference/fs-rtp-special-source.c b/gst/fsrtpconference/fs-rtp-special-source.c
index 804a3a6..9c42958 100644
--- a/gst/fsrtpconference/fs-rtp-special-source.c
+++ b/gst/fsrtpconference/fs-rtp-special-source.c
@@ -66,6 +66,7 @@ struct _FsRtpSpecialSourcePrivate {
 
   GThread *stop_thread;
 
+  /* Protects the content of this struct after object has been disposed of */
   GMutex *mutex;
 };
 
@@ -171,6 +172,13 @@ fs_rtp_special_source_init (FsRtpSpecialSource *self)
   self->priv->mutex = g_mutex_new ();
 }
 
+/**
+ * stop_source_thread:
+ * @data: a pointer to the current #FsRtpSpecialSource
+ *
+ * This functioin will lock on the source's state change until its release
+ * and only then let the source be disposed of
+ */
 
 static gpointer
 stop_source_thread (gpointer data)
@@ -334,6 +342,17 @@ fs_rtp_special_source_class_want_source (FsRtpSpecialSourceClass *klass,
   return FALSE;
 }
 
+/**
+ * fs_rtp_special_sources_add_blueprints:
+ * @blueprints: a #GList of #CodecBlueprint
+ *
+ * This function will add blueprints to the current list of blueprints based
+ * on which elements are installed and on which codecs are already in the list
+ * of blueprints.
+ *
+ * Returns: The updated #GList of #CodecBlueprint
+ */
+
 GList *
 fs_rtp_special_sources_add_blueprints (GList *blueprints)
 {
@@ -546,6 +565,15 @@ fs_rtp_special_source_update (FsRtpSpecialSource *source,
   return FALSE;
 }
 
+/**
+ * fs_rtp_special_source_send_event:
+ * @self: a #FsRtpSpecialSource
+ * @event: a upstream #GstEvent to send
+ *
+ * Sends an upstream event to the source.
+ *
+ * Returns: %TRUE if the event was delivered succesfully, %FALSE otherwise
+ */
 
 static gboolean
 fs_rtp_special_source_send_event (FsRtpSpecialSource *self,
@@ -570,6 +598,17 @@ fs_rtp_special_source_send_event (FsRtpSpecialSource *self,
   return ret;
 }
 
+/**
+ * fs_rtp_special_sources_send_event:
+ * @current_extra_sources: The #GList of current #FsRtpSpecialSource
+ * @event: an upstream #GstEvent
+ *
+ * This function will try to deliver the events in the specified order to the
+ * special sources, it will stop once one source has accepted the event.
+ *
+ * Returns: %TRUE if a sources accepted the event, %FALSE otherwise
+ */
+
 static gboolean
 fs_rtp_special_sources_send_event (GList *current_extra_sources,
     GstEvent *event)
diff --git a/gst/fsrtpconference/fs-rtp-special-source.h b/gst/fsrtpconference/fs-rtp-special-source.h
index 8b54ce9..8763c8d 100644
--- a/gst/fsrtpconference/fs-rtp-special-source.h
+++ b/gst/fsrtpconference/fs-rtp-special-source.h
@@ -54,6 +54,25 @@ typedef struct _FsRtpSpecialSource FsRtpSpecialSource;
 typedef struct _FsRtpSpecialSourceClass FsRtpSpecialSourceClass;
 typedef struct _FsRtpSpecialSourcePrivate FsRtpSpecialSourcePrivate;
 
+/**
+ * FsRtpSpecialSourceClass:
+ * @build: The method builds the source #GstElement from the list of negotiated
+ *   codecs and selected codecs, it returns %NULL and sets the #GError on error
+ * @update: This optional method can update the content of the current source
+ *  if its possible. If the source can not be modified, it returns %FALSE (and
+ *  a new source will be created)
+ * @want_source: Returns %TRUE if a source of this type should be created
+ *  according to the selected codec and the negotiated codecs
+ * @add_blueprint: Adds #CodecBlueprint structs to the list if the proper
+ *  elements are installed, the result should always be the same if the elements
+ *  installed don't change. It must fill the #CodecBlueprint completely except
+ *  for the send_pipeline_factory field. If no blueprints are installed by this
+ *  class, this method is not required.
+ *
+ * Class structure for #FsRtpSpecialSource, the build() and want_source()
+ * methods are required.
+ */
+
 struct _FsRtpSpecialSourceClass
 {
   GObjectClass parent_class;
@@ -80,7 +99,8 @@ struct _FsRtpSpecialSourceClass
 
 /**
  * FsRtpSpecialSource:
- *
+ * @order: a number between 0 and 100 that defines in which order the sources
+ * will be traversed in order to send events to them.
  */
 struct _FsRtpSpecialSource
 {
-- 
1.5.6.5