first stab at documenting elements

Original commit message from CVS:
first stab at documenting elements
parent 70f589da
2005-08-05 Thomas Vander Stichele <thomas at apestaart dot org>
* common/Makefile.am:
* common/gstdoc-scangobj:
* common/gtk-doc-plugins.mak:
* common/gtk-doc.mak:
add a custom scangobj that uses the registry
add a custom gtk-doc-plugins.mak that uses it
some doc build fixes
* configure.ac:
* docs/Makefile.am:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-base-plugins-docs.sgml:
* docs/plugins/gst-plugins-base-plugins-sections.txt:
* docs/plugins/gst-plugins-base-plugins.types:
* docs/plugins/tmpl/gstmultifdsink.sgml:
add docs for one element, multifdsink
* gst/adder/gstadder.h:
* gst/volume/gstvolume.h:
don't privatize enum
* gst/tcp/gstfdset.c: (gst_fdset_mode_get_type):
* gst/tcp/gstmultifdsink.c: (gst_recover_policy_get_type),
(gst_sync_method_get_type), (gst_client_status_get_type),
(gst_multifdsink_class_init),
(gst_multifdsink_client_queue_buffer),
(gst_multifdsink_handle_client_write):
* gst/tcp/gstmultifdsink.h:
* gst/tcp/gsttcp.h:
* gst/tcp/gsttcpclientsink.c: (gst_tcpclientsink_class_init),
(gst_tcpclientsink_init), (gst_tcpclientsink_setcaps),
(gst_tcpclientsink_render):
* gst/tcp/gsttcpclientsink.h:
* gst/tcp/gsttcpclientsrc.c: (gst_tcpclientsrc_class_init),
(gst_tcpclientsrc_init), (gst_tcpclientsrc_create),
(gst_tcpclientsrc_start):
* gst/tcp/gsttcpclientsrc.h:
* gst/tcp/gsttcpserversrc.c: (gst_tcpserversrc_class_init),
(gst_tcpserversrc_init), (gst_tcpserversrc_create):
* gst/tcp/gsttcpserversrc.h:
* gst/typefind/gsttypefindfunctions.c:
remove superfluous Type stuff
2005-08-05 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
* gst/playback/gstplaybin.c: (gen_video_element):
......
common @ c99f9050
Subproject commit 694de4dbf4827f372321f0634643a254d7edd986
Subproject commit c99f9050f296219783c6717efe319dc741d2e2d3
......@@ -929,6 +929,7 @@ pkgconfig/gstreamer-plugins-base.pc
pkgconfig/gstreamer-plugins-base-uninstalled.pc
docs/Makefile
docs/libs/Makefile
docs/plugins/Makefile
docs/version.entities
po/Makefile.in
common/Makefile
......
version.entities
if ENABLE_GTK_DOC
GTK_DOC_DIRS = libs
GTK_DOC_DIRS = libs # plugins
else
GTK_DOC_DIRS =
endif
SUBDIRS = $(GTK_DOC_DIRS)
DIST_SUBDIRS = libs
DIST_SUBDIRS = libs plugins
EXTRA_DIST = \
upload.mak \
......
......@@ -3,13 +3,13 @@ html
xml
Makefile
Makefile.in
gst-plugins-base-libs-decl.txt
gst-plugins-base-libs-decl-list.txt
gst-plugins-base-libs-presed-scan.c
gst-plugins-base-libs-undocumented.txt
gst-plugins-base-libs-unused.txt
gst-plugins-base-libs.args
gst-plugins-base-libs.hierarchy
gst-plugins-base-libs.interfaces
gst-plugins-base-libs.prerequisites
gst-plugins-base-libs.signals
*-decl.txt
*-decl-list.txt
*-presed-scan.c
*-undocumented.txt
*-unused.txt
*.args
*.hierarchy
*.interfaces
*.prerequisites
*.signals
*-unused.sgml
*.bak
Makefile
Makefile.in
*-decl.txt
*-decl-list.txt
*-undocumented.txt
*-unused.txt
*.args
*.hierarchy
*.interfaces
*.prerequisites
*.signals
html
sgml
xml
*.stamp
GST_DOC_SCANOBJ = $(top_srcdir)/common/gstdoc-scangobj
## Process this file with automake to produce Makefile.in
# The name of the module, e.g. 'glib'.
#DOC_MODULE=gst-plugins-libs-@GST_MAJORMINOR@
DOC_MODULE=gst-plugins-base-plugins
# for upload.mak
DOC=gst-plugins-base-plugins
FORMATS=html
html: html-build.stamp
include $(srcdir)/../upload.mak
# generated basefiles
#basefiles = \
## $(DOC_MODULE).types \
# $(DOC_MODULE)-sections.txt \
# $(DOC_MODULE)-docs.sgml
# ugly hack to make -unused.sgml work
#unused-build.stamp:
# BUILDDIR=`pwd` && \
# cd $(srcdir)/tmpl && \
# ln -sf gstreamer-libs-unused.sgml \
# $$BUILDDIR/tmpl/gstreamer-libs-@GST_MAJORMINOR@-unused.sgml
# touch unused-build.stamp
# these rules are added to create parallel docs using GST_MAJORMINOR
#$(basefiles): gstreamer-libs-@GST_MAJORMINOR@%: gstreamer-libs%
# cp $< $@
#CLEANFILES = $(basefiles)
# The top-level SGML file. Change it if you want.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# The directory containing the source code. Relative to $(top_srcdir).
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting functions and macros.
DOC_SOURCE_DIR = $(top_srcdir)
# Extra options to supply to gtkdoc-scan.
SCAN_OPTIONS=
# FIXME :
# there's something wrong with gstreamer-sections.txt not being in the dist
# maybe it doesn't resolve; we're adding it below for now
#EXTRA_DIST = gstreamer.types.in gstreamer.hierarchy $(DOC_MODULE)-sections.txt gstreamer-sections.txt $(DOC_MAIN_SGML_FILE)
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--sgml-mode --ignore-files=trio
# Extra options to supply to gtkdoc-fixref.
# FIXME get the location of the installed gstreamer docs
#FIXXREF_OPTIONS=--extra-dir=../gst/html
# Used for dependencies.
HFILE_GLOB=$(DOC_SOURCE_DIR)/*/*/*.h
CFILE_GLOB=$(DOC_SOURCE_DIR)/*/*/*.c
# this is a wingo addition
# thomasvs: another nice wingo addition would be an explanation on why
# this is useful ;)
SCANOBJ_DEPS =
# Header files to ignore when scanning.
IGNORE_HFILES = avcodec.h gstffmpegcodecmap.h
EXTRA_HFILES = $(top_srcdir)/gst/tcp/gstmultifdsink.h
# Images to copy into HTML directory.
HTML_IMAGES =
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
content_files =
# Other files to distribute.
extra_files =
# CFLAGS and LDFLAGS for compiling scan program. Only needed if your app/lib
# contains GtkObjects/GObjects and you want to document signals and properties.
GTKDOC_CFLAGS = $(GST_BASE_CFLAGS) -I$(top_builddir) -I$(top_builddir)/gst-libs
GTKDOC_LIBS = $(SCANOBJ_DEPS) $(GST_BASE_LIBS)
GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
# If you need to override some of the declarations, place them in this file
# and uncomment this line.
#DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
DOC_OVERRIDES =
include $(top_srcdir)/common/gtk-doc-plugins.mak
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>gst-plugins-base Plugins Reference Manual</title>
</bookinfo>
<chapter>
<title>gst-plugins-base Plugins</title>
<xi:include href="xml/gstmultifdsink.xml"/>
</chapter>
</book>
<SECTION>
<FILE>gstmultifdsink</FILE>
GstMultiFdSink
GstMultiFdSinkFlags
GstRecoverPolicy
GstSyncMethod
GstUnitType
GstClientStatus
<TITLE>GstMultiFdSink</TITLE>
<SUBSECTION Standard>
GstMultiFdSinkClass
</SECTION>
<!-- ##### SECTION Title ##### -->
GstMultiFdSink
<!-- ##### SECTION Short_Description ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### STRUCT GstMultiFdSink ##### -->
<para>
</para>
<!-- ##### SIGNAL GstMultiFdSink::add ##### -->
<para>
</para>
@gstmultifdsink: the object which received the signal.
@arg1:
<!-- ##### SIGNAL GstMultiFdSink::clear ##### -->
<para>
</para>
@gstmultifdsink: the object which received the signal.
<!-- ##### SIGNAL GstMultiFdSink::client-added ##### -->
<para>
</para>
@gstmultifdsink: the object which received the signal.
@arg1:
<!-- ##### SIGNAL GstMultiFdSink::client-removed ##### -->
<para>
</para>
@gstmultifdsink: the object which received the signal.
@arg1:
@arg2:
<!-- ##### SIGNAL GstMultiFdSink::get-stats ##### -->
<para>
</para>
@gstmultifdsink: the object which received the signal.
@arg1:
@Returns:
<!-- ##### SIGNAL GstMultiFdSink::remove ##### -->
<para>
</para>
@gstmultifdsink: the object which received the signal.
@arg1:
<!-- ##### ARG GstMultiFdSink:buffers-max ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:buffers-queued ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:buffers-soft-max ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:bytes-served ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:bytes-to-serve ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:mode ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:protocol ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:recover-policy ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:sync-clients ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:sync-method ##### -->
<para>
</para>
<!-- ##### ARG GstMultiFdSink:timeout ##### -->
<para>
</para>
<!-- ##### ENUM GstMultiFdSinkFlags ##### -->
<para>
</para>
@GST_MULTIFDSINK_OPEN:
@GST_MULTIFDSINK_FLAG_LAST:
<!-- ##### ENUM GstRecoverPolicy ##### -->
<para>
</para>
@GST_RECOVER_POLICY_NONE:
@GST_RECOVER_POLICY_RESYNC_START:
@GST_RECOVER_POLICY_RESYNC_SOFT:
@GST_RECOVER_POLICY_RESYNC_KEYFRAME:
<!-- ##### ENUM GstSyncMethod ##### -->
<para>
</para>
@GST_SYNC_METHOD_NONE:
@GST_SYNC_METHOD_WAIT:
@GST_SYNC_METHOD_BURST:
<!-- ##### ENUM GstUnitType ##### -->
<para>
</para>
@GST_UNIT_TYPE_BUFFERS:
@GST_UNIT_TYPE_TIME:
@GST_UNIT_TYPE_BYTES:
<!-- ##### ENUM GstClientStatus ##### -->
<para>
</para>
@GST_CLIENT_STATUS_OK:
@GST_CLIENT_STATUS_CLOSED:
@GST_CLIENT_STATUS_REMOVED:
@GST_CLIENT_STATUS_SLOW:
@GST_CLIENT_STATUS_ERROR:
@GST_CLIENT_STATUS_DUPLICATE:
......@@ -44,13 +44,12 @@ extern GstElementDetails gst_adder_details;
typedef struct _GstAdder GstAdder;
typedef struct _GstAdderClass GstAdderClass;
typedef struct _GstAdderInputChannel GstAdderInputChannel;
typedef enum _GstAdderFormat GstAdderFormat;
enum _GstAdderFormat {
typedef enum {
GST_ADDER_FORMAT_UNSET,
GST_ADDER_FORMAT_INT,
GST_ADDER_FORMAT_FLOAT
};
} GstAdderFormat;
typedef void (*GstAdderFunction) (gpointer out, gpointer in, guint size);
......
......@@ -44,7 +44,7 @@ gst_fdset_mode_get_type (void)
};
if (!fdset_mode_type) {
fdset_mode_type = g_enum_register_static ("GstFDSetModeType", fdset_mode);
fdset_mode_type = g_enum_register_static ("GstFDSetMode", fdset_mode);
}
return fdset_mode_type;
}
......
......@@ -91,7 +91,7 @@ enum
};
/* this is really arbitrarily chosen */
#define DEFAULT_PROTOCOL GST_TCP_PROTOCOL_TYPE_NONE
#define DEFAULT_PROTOCOL GST_TCP_PROTOCOL_NONE
#define DEFAULT_MODE GST_FDSET_MODE_POLL
#define DEFAULT_BUFFERS_MAX -1
#define DEFAULT_BUFFERS_SOFT_MAX -1
......@@ -145,7 +145,7 @@ gst_recover_policy_get_type (void)
if (!recover_policy_type) {
recover_policy_type =
g_enum_register_static ("GstTCPRecoverPolicy", recover_policy);
g_enum_register_static ("GstRecoverPolicy", recover_policy);
}
return recover_policy_type;
}
......@@ -166,7 +166,7 @@ gst_sync_method_get_type (void)
};
if (!sync_method_type) {
sync_method_type = g_enum_register_static ("GstTCPSyncMethod", sync_method);
sync_method_type = g_enum_register_static ("GstSyncMethod", sync_method);
}
return sync_method_type;
}
......@@ -208,7 +208,7 @@ gst_client_status_get_type (void)
if (!client_status_type) {
client_status_type =
g_enum_register_static ("GstTCPClientStatus", client_status);
g_enum_register_static ("GstClientStatus", client_status);
}
return client_status_type;
}
......@@ -291,7 +291,7 @@ gst_multifdsink_class_init (GstMultiFdSinkClass * klass)
g_object_class_install_property (gobject_class, ARG_PROTOCOL,
g_param_spec_enum ("protocol", "Protocol", "The protocol to wrap data in",
GST_TYPE_TCP_PROTOCOL_TYPE, DEFAULT_PROTOCOL, G_PARAM_READWRITE));
GST_TYPE_TCP_PROTOCOL, DEFAULT_PROTOCOL, G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, ARG_MODE,
g_param_spec_enum ("mode", "Mode",
"The mode for selecting activity on the fds", GST_TYPE_FDSET_MODE,
......@@ -361,14 +361,34 @@ gst_multifdsink_class_init (GstMultiFdSinkClass * klass)
"Total number of bytes send to all clients", 0, G_MAXUINT64, 0,
G_PARAM_READABLE));
/**
* GstMultiFdSink::add:
* @gstmultifdsink: the multifdsink element to emit this signal on
* @arg1: the file descriptor to add to multifdsink
*
* Hand the given open file descriptor to multifdsink to write to.
*/
gst_multifdsink_signals[SIGNAL_ADD] =
g_signal_new ("add", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstMultiFdSinkClass, add),
NULL, NULL, g_cclosure_marshal_VOID__INT, G_TYPE_NONE, 1, G_TYPE_INT);
/**
* GstMultiFdSink::remove:
* @gstmultifdsink: the multifdsink element to emit this signal on
* @arg1: the file descriptor to remove from multifdsink
*
* Remove the given open file descriptor from multifdsink.
*/
gst_multifdsink_signals[SIGNAL_REMOVE] =
g_signal_new ("remove", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstMultiFdSinkClass, remove),
NULL, NULL, gst_tcp_marshal_VOID__INT, G_TYPE_NONE, 1, G_TYPE_INT);
/**
* GstMultiFdSink::clear:
* @gstmultifdsink: the multifdsink element to emit this signal on
*
* Clear all file descriptors from multifdsink.
*/
gst_multifdsink_signals[SIGNAL_CLEAR] =
g_signal_new ("clear", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstMultiFdSinkClass, clear),
......@@ -379,10 +399,24 @@ gst_multifdsink_class_init (GstMultiFdSinkClass * klass)
NULL, NULL, gst_tcp_marshal_BOXED__INT, G_TYPE_VALUE_ARRAY, 1,
G_TYPE_INT);
/**
* GstMultiFdSink::client-added:
* @gstmultifdsink: the multifdsink element that emitted this signal
* @arg1: the file descriptor that was added to multifdsink
*
* The given file descriptor was added to multifdsink.
*/
gst_multifdsink_signals[SIGNAL_CLIENT_ADDED] =
g_signal_new ("client-added", G_TYPE_FROM_CLASS (klass),
G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstMultiFdSinkClass, client_added),
NULL, NULL, gst_tcp_marshal_VOID__INT, G_TYPE_NONE, 1, G_TYPE_INT);
/**
* GstMultiFdSink::client-removed:
* @gstmultifdsink: the multifdsink element that emitted this signal
* @arg1: the file descriptor that was removed from multifdsink
*
* The given file descriptor was removed from multifdsink.
*/
gst_multifdsink_signals[SIGNAL_CLIENT_REMOVED] =
g_signal_new ("client-removed", G_TYPE_FROM_CLASS (klass),
G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstMultiFdSinkClass,
......@@ -802,7 +836,7 @@ static gboolean
gst_multifdsink_client_queue_buffer (GstMultiFdSink * sink,
GstTCPClient * client, GstBuffer * buffer)
{
if (sink->protocol == GST_TCP_PROTOCOL_TYPE_GDP) {
if (sink->protocol == GST_TCP_PROTOCOL_GDP) {
guint8 *header;
guint len;
......@@ -945,7 +979,7 @@ gst_multifdsink_handle_client_write (GstMultiFdSink * sink,
now = GST_TIMEVAL_TO_TIME (nowtv);
/* when using GDP, first check if we have queued caps yet */
if (sink->protocol == GST_TCP_PROTOCOL_TYPE_GDP) {
if (sink->protocol == GST_TCP_PROTOCOL_GDP) {
if (!client->caps_sent) {
const GstCaps *caps =
GST_PAD_CAPS (GST_PAD_PEER (GST_BASE_SINK_PAD (sink)));
......
......@@ -100,7 +100,7 @@ typedef struct {
gboolean discont;
GstTCPProtocolType protocol;
GstTCPProtocol protocol;
gboolean caps_sent;
gboolean streamheader_sent;
......@@ -139,7 +139,7 @@ struct _GstMultiFdSink {
GSList *streamheader; /* GSList of GstBuffers to use as streamheader */
gboolean previous_buffer_in_caps;
GstTCPProtocolType protocol;
GstTCPProtocol protocol;
guint mtu;
GArray *bufqueue; /* global queue of buffers */
......
......@@ -35,9 +35,9 @@ G_BEGIN_DECLS
typedef enum
{
GST_TCP_PROTOCOL_TYPE_NONE,
GST_TCP_PROTOCOL_TYPE_GDP
} GstTCPProtocolType;
GST_TCP_PROTOCOL_NONE,
GST_TCP_PROTOCOL_GDP
} GstTCPProtocol;
gchar * gst_tcp_host_to_ip (GstElement *element, const gchar *host);
......
......@@ -134,8 +134,7 @@ gst_tcpclientsink_class_init (GstTCPClientSink * klass)
0, TCP_HIGHEST_PORT, TCP_DEFAULT_PORT, G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, ARG_PROTOCOL,
g_param_spec_enum ("protocol", "Protocol", "The protocol to wrap data in",
GST_TYPE_TCP_PROTOCOL_TYPE, GST_TCP_PROTOCOL_TYPE_NONE,
G_PARAM_READWRITE));
GST_TYPE_TCP_PROTOCOL, GST_TCP_PROTOCOL_NONE, G_PARAM_READWRITE));
gstelement_class->change_state = gst_tcpclientsink_change_state;
......@@ -152,7 +151,7 @@ gst_tcpclientsink_init (GstTCPClientSink * this)
this->port = TCP_DEFAULT_PORT;
this->sock_fd = -1;
this->protocol = GST_TCP_PROTOCOL_TYPE_NONE;
this->protocol = GST_TCP_PROTOCOL_NONE;
GST_FLAG_UNSET (this, GST_TCPCLIENTSINK_OPEN);
}
......@@ -173,10 +172,10 @@ gst_tcpclientsink_setcaps (GstBaseSink * bsink, GstCaps * caps)
/* write the buffer header if we have one */
switch (sink->protocol) {
case GST_TCP_PROTOCOL_TYPE_NONE:
case GST_TCP_PROTOCOL_NONE:
break;
case GST_TCP_PROTOCOL_TYPE_GDP:
case GST_TCP_PROTOCOL_GDP:
/* if we haven't send caps yet, send them first */
if (!sink->caps_sent) {
const GstCaps *caps;
......@@ -226,9 +225,9 @@ gst_tcpclientsink_render (GstBaseSink * bsink, GstBuffer * buf)
/* write the buffer header if we have one */
switch (sink->protocol) {
case GST_TCP_PROTOCOL_TYPE_NONE:
case GST_TCP_PROTOCOL_NONE:
break;
case GST_TCP_PROTOCOL_TYPE_GDP:
case GST_TCP_PROTOCOL_GDP:
GST_LOG_OBJECT (sink, "Sending buffer header through GDP");
if (!gst_tcp_gdp_write_buffer (GST_ELEMENT (sink), sink->sock_fd, buf,
TRUE, sink->host, sink->port))
......
......@@ -76,7 +76,7 @@ struct _GstTCPClientSink {
int sock_fd;
size_t data_written; /* how much bytes have we written ? */
GstTCPProtocolType protocol; /* used with the protocol enum */
GstTCPProtocol protocol; /* used with the protocol enum */
gboolean caps_sent; /* whether or not we sent caps already */
};
......
......@@ -153,8 +153,7 @@ gst_tcpclientsrc_class_init (GstTCPClientSrc * klass)
TCP_HIGHEST_PORT, TCP_DEFAULT_PORT, G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, ARG_PROTOCOL,
g_param_spec_enum ("protocol", "Protocol", "The protocol to wrap data in",