[farsight2/master] Document object structures and classes

[Olivier Crête]

---
 gst-libs/gst/farsight/fs-base-conference.h    |   22 +++++++++++++++++++++-
 gst-libs/gst/farsight/fs-participant.h        |   14 ++++++++++++--
 gst-libs/gst/farsight/fs-session.h            |   16 +++++++++++++++-
 gst-libs/gst/farsight/fs-stream-transmitter.h |    9 +++++++++
 gst-libs/gst/farsight/fs-stream.h             |   15 ++++++++++++++-
 gst-libs/gst/farsight/fs-transmitter.h        |    9 +++++++++
 6 files changed, 80 insertions(+), 5 deletions(-)

diff --git a/gst-libs/gst/farsight/fs-base-conference.h b/gst-libs/gst/farsight/fs-base-conference.h
index bb4c8f5..a66fbf0 100644
--- a/gst-libs/gst/farsight/fs-base-conference.h
+++ b/gst-libs/gst/farsight/fs-base-conference.h
@@ -54,16 +54,34 @@ typedef struct _FsBaseConference FsBaseConference;
 typedef struct _FsBaseConferenceClass FsBaseConferenceClass;
 typedef struct _FsBaseConferencePrivate FsBaseConferencePrivate;
 
+/**
+ * FsBaseConference
+ *
+ * The #FsBaseConference structure, all the members are private
+ */
+
 struct _FsBaseConference
 {
   GstBin parent;
-  FsBaseConferencePrivate *priv;
 
   /*< private >*/
 
+  FsBaseConferencePrivate *priv;
+
   gpointer _padding[8];
 };
 
+/**
+ * FsBaseConferenceClass:
+ * @parent_class: Our parent
+ * @new_session: allocates a new #FsSession for this conference
+ * @new_participant: Creates a new #FsParticipant of the type required for
+ * this conference
+ *
+ * The class structure of #FsBaseConference. Derived classes should override
+ * all members.
+ */
+
 struct _FsBaseConferenceClass
 {
   GstBinClass parent_class;
@@ -76,6 +94,8 @@ struct _FsBaseConferenceClass
   FsParticipant *(*new_participant) (FsBaseConference *conference,
                                      gchar *cname);
 
+  /*< private >*/
+
   gpointer _padding[8];
 };
 
diff --git a/gst-libs/gst/farsight/fs-participant.h b/gst-libs/gst/farsight/fs-participant.h
index b4eb84f..4382fe5 100644
--- a/gst-libs/gst/farsight/fs-participant.h
+++ b/gst-libs/gst/farsight/fs-participant.h
@@ -49,11 +49,19 @@ typedef struct _FsParticipant FsParticipant;
 typedef struct _FsParticipantClass FsParticipantClass;
 typedef struct _FsParticipantPrivate FsParticipantPrivate;
 
+/**
+ * FsParticipantClass:
+ * @parent_class: Our parent
+ *
+ * The FsParticipant class has no virtual methods to implement,
+ * but you may want to override the properties or attach more date to it
+ */
+
 struct _FsParticipantClass
 {
   GObjectClass parent_class;
 
-  /*virtual functions */
+  /* virtual functions */
 
   /*< private >*/
   FsParticipantPrivate *priv;
@@ -63,14 +71,16 @@ struct _FsParticipantClass
 /**
  * FsParticipant:
  *
+ * All members are private (access them using the properties)
  */
 struct _FsParticipant
 {
   GObject parent;
-  FsParticipantPrivate *priv;
 
   /*< private >*/
 
+  FsParticipantPrivate *priv;
+
   gpointer _padding[8];
 };
 
diff --git a/gst-libs/gst/farsight/fs-session.h b/gst-libs/gst/farsight/fs-session.h
index 737333b..d58ee2c 100644
--- a/gst-libs/gst/farsight/fs-session.h
+++ b/gst-libs/gst/farsight/fs-session.h
@@ -121,6 +121,18 @@ typedef enum {
 
 GQuark fs_session_error_quark (void);
 
+/**
+ * FsSessionClass:
+ * @parent_class: Our parent
+ * @new_stream: Create a new #FsStream
+ * @start_telephony_event: Starts a telephony event
+ * @stop_telephony_event: Stops a telephony event
+ * @set_send_codec: Forces sending with a specific codec
+ *
+ * You must override at least new_stream in a subclass.
+ */
+
+
 struct _FsSessionClass
 {
   GObjectClass parent_class;
@@ -146,13 +158,15 @@ struct _FsSessionClass
 /**
  * FsSession:
  *
+ * All members are private, access them using methods and properties
  */
 struct _FsSession
 {
   GObject parent;
+  /*< private >*/
+
   FsSessionPrivate *priv;
 
-  /*< private >*/
 
   gpointer _padding[8];
 };
diff --git a/gst-libs/gst/farsight/fs-stream-transmitter.h b/gst-libs/gst/farsight/fs-stream-transmitter.h
index f2a89e7..4b22bdf 100644
--- a/gst-libs/gst/farsight/fs-stream-transmitter.h
+++ b/gst-libs/gst/farsight/fs-stream-transmitter.h
@@ -54,6 +54,14 @@ typedef struct _FsStreamTransmitter FsStreamTransmitter;
 typedef struct _FsStreamTransmitterClass FsStreamTransmitterClass;
 typedef struct _FsStreamTransmitterPrivate FsStreamTransmitterPrivate;
 
+/**
+ * FsStreamTransmitterClass:
+ * @parent_class: Our parent
+ * @add_remote_candidate: Sets the remote candidate
+ *
+ * You must override the add_remote_candidate in a subclass
+ */
+
 struct _FsStreamTransmitterClass
 {
   GObjectClass parent_class;
@@ -69,6 +77,7 @@ struct _FsStreamTransmitterClass
 /**
  * FsStreamTransmitter:
  *
+ * All members are private, access them using methods and properties
  */
 struct _FsStreamTransmitter
 {
diff --git a/gst-libs/gst/farsight/fs-stream.h b/gst-libs/gst/farsight/fs-stream.h
index 047c229..a245176 100644
--- a/gst-libs/gst/farsight/fs-stream.h
+++ b/gst-libs/gst/farsight/fs-stream.h
@@ -97,6 +97,17 @@ typedef enum {
 
 GQuark fs_stream_error_quark (void);
 
+/**
+ * FsStreamClass:
+ * @parent_class: Our parent
+ * @add_remote_candidate: Adds a remote candidate
+ * @preload_recv_codec: Set which codec to prelaod
+ * @set_remote_codecs: Sets the list of remote codecs
+ *
+ * You must override add_remote_candidate in a subclass.
+ * If you have to negotiate codecs, then you must override set_remote_codecs too
+ */
+
 struct _FsStreamClass
 {
   GObjectClass parent_class;
@@ -119,14 +130,16 @@ struct _FsStreamClass
 /**
  * FsStream:
  *
+ * All members are private, access them using methods and properties
  */
 struct _FsStream
 {
   GObject parent;
-  FsStreamPrivate *priv;
 
   /*< private >*/
 
+  FsStreamPrivate *priv;
+
   gpointer _padding[8];
 };
 
diff --git a/gst-libs/gst/farsight/fs-transmitter.h b/gst-libs/gst/farsight/fs-transmitter.h
index 3df4431..c42ff67 100644
--- a/gst-libs/gst/farsight/fs-transmitter.h
+++ b/gst-libs/gst/farsight/fs-transmitter.h
@@ -52,6 +52,14 @@ typedef struct _FsTransmitter FsTransmitter;
 typedef struct _FsTransmitterClass FsTransmitterClass;
 typedef struct _FsTransmitterPrivate FsTransmitterPrivate;
 
+/**
+ * FsTransmitterClass:
+ * @parent_class: Our parent
+ * @new_stream_transmitter: Creates a new #FsStreamTransmitter
+ *
+ * You must override the new_stream_transmitter method in a subclass
+ */
+
 struct _FsTransmitterClass
 {
   GObjectClass parent_class;
@@ -67,6 +75,7 @@ struct _FsTransmitterClass
 /**
  * FsTransmitter:
  *
+ * All members are private, access them using methods and properties
  */
 struct _FsTransmitter
 {
-- 
1.5.6.5