docs: Add gtk-doc API documentation

current coverage : 8%

Makefile.am

@@ -1,8 +1,8 @@
 DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
 
-SUBDIRS = ges tests common m4
+SUBDIRS = ges tests common m4 docs
 
-DIST_SUBDIRS = ges tests common m4
+DIST_SUBDIRS = $(SUBDIRS)
 
 # include before EXTRA_DIST for win32 assignment
 #include $(top_srcdir)/common/win32.mak

configure.ac

@@ -243,5 +243,8 @@ ges/Makefile
 tests/Makefile
 tests/check/Makefile
 tests/examples/Makefile
+docs/Makefile
+docs/version.entities
+docs/libs/Makefile
 )
 AC_OUTPUT

docs/Makefile.am

@@ -0,0 +1,11 @@
+if ENABLE_GTK_DOC
+DOCS_SUBDIRS = libs
+else
+DOCS_SUBDIRS = 
+endif
+
+SUBDIRS = $(DOCS_SUBDIRS)
+DIST_SUBDIRS = libs
+
+EXTRA_DIST = \
+	version.entities.in

docs/libs/Makefile.am

@@ -0,0 +1,103 @@
+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'.
+MODULE=ges
+DOC_MODULE=$(MODULE)
+
+# for upload-doc.mak
+DOC=$(MODULE)
+FORMATS=html
+html: html-build.stamp
+include $(top_srcdir)/common/upload-doc.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)/ges/
+
+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 --source-suffixes=c,h,cc,m
+
+# Extra options to supply to gtkdoc-fixref.
+FIXXREF_OPTIONS=--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html \
+	--extra-dir=$(GST_PREFIX)/share/gtk-doc/html \
+	--extra-dir=$(GSTPB_PREFIX)/share/gtk-doc/html
+
+# Used for dependencies.
+HFILE_GLOB=$(DOC_SOURCE_DIR)/ges-*.h
+CFILE_GLOB=$(DOC_SOURCE_DIR)/ges-*.c
+
+SCANOBJ_DEPS = 
+# Extra options to supply to gtkdoc-scan.
+SCANOBJ_OPTIONS=--type-init-func="g_type_init();gst_init(&argc,&argv)"
+
+# Header files to ignore when scanning.
+IGNORE_HFILES = gesmarshal.h ges-internal.h
+IGNORE_CFILES =
+
+# we add all .h files of elements that have signals/args we want
+# sadly this also pulls in the private methods - maybe we should
+# move those around in the source ?
+# also, we should add some stuff here conditionally based on whether
+# or not the plugin will actually build
+# but I'm not sure about that - it might be this Just Works given that
+# the registry won't have the element
+
+EXTRA_HFILES = \
+	$(top_srcdir)/ges/ges-types.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)
+GTKDOC_LIBS = $(SCANOBJ_DEPS) $(GST_BASE_LIBS)
+
+GTKDOC_CC=$(LIBTOOL) --tag=CC --mode=compile $(CC)
+GTKDOC_LD=$(LIBTOOL) --tag=CC --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.mak

docs/libs/ges-docs.sgml

@@ -0,0 +1,41 @@
+<?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" [
+<!ENTITY % version-entities SYSTEM "version.entities">
+%version-entities;
+]>
+
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>GStreamer Editing Services &GES_VERSION; Reference Manual</title>
+    <releaseinfo>
+      for GStreamer Editing Services &GST_MAJORMINOR; (&GES_VERSION;)
+    </releaseinfo>
+  </bookinfo>
+
+  <xi:include href="xml/ges.xml"/>
+
+  <chapter>
+    <title>Base Classes</title>
+    <xi:include href="xml/ges-track.xml"/>
+    <xi:include href="xml/ges-track-object.xml"/>
+    <xi:include href="xml/ges-track-source.xml"/>
+    <xi:include href="xml/ges-timeline.xml"/>
+    <xi:include href="xml/ges-timeline-layer.xml"/>
+    <xi:include href="xml/ges-timeline-object.xml"/>
+    <xi:include href="xml/ges-timeline-source.xml"/>
+    <xi:include href="xml/ges-timeline-transition.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Simple Timeline interface</title>
+    <xi:include href="xml/ges-simple-timeline-layer.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Convenience classes</title>
+    <xi:include href="xml/ges-timeline-pipeline.xml"/>
+    <xi:include href="xml/ges-custom-timeline-source.xml"/>
+  </chapter>
+
+</book>

docs/libs/ges-sections.txt

@@ -0,0 +1,229 @@
+<INCLUDE>ges/ges.h</INCLUDE>
+
+<SECTION>
+<FILE>ges</FILE>
+<TITLE>GStreamer Editing Services</TITLE>
+ges_init
+</SECTION>
+
+<FILE>ges-track</FILE>
+<TITLE>GESTrack</TITLE>
+GESTrack
+GESTrackClass
+FillTrackObjectFunc
+FillTrackObjectUserFunc
+GESTrackType
+ges_track_add_object
+ges_track_audio_raw_new
+ges_track_get_type
+ges_track_new
+ges_track_remove_object
+ges_track_set_caps
+ges_track_set_timeline
+ges_track_video_raw_new
+<SUBSECTION Standard>
+ges_track_type_get_type
+GES_IS_TRACK
+GES_IS_TRACK_CLASS
+GES_TRACK
+GES_TRACK_CLASS
+GES_TRACK_GET_CLASS
+GES_TYPE_TRACK
+GES_TYPE_TRACK_TYPE
+</SECTION>
+
+<SECTION>
+<FILE>ges-track-object</FILE>
+<TITLE>GESTrackObject</TITLE>
+GESTrackObject
+GESTrackObjectClass
+ges_track_object_new
+ges_track_object_set_duration_internal
+ges_track_object_set_inpoint_internal
+ges_track_object_set_priority_internal
+ges_track_object_set_start_internal
+ges_track_object_set_timeline_object
+ges_track_object_set_track
+<SUBSECTION Standard>
+ges_track_object_get_type
+GES_IS_TRACK_OBJECT
+GES_IS_TRACK_OBJECT_CLASS
+GES_TRACK_OBJECT
+GES_TRACK_OBJECT_CLASS
+GES_TRACK_OBJECT_GET_CLASS
+GES_TYPE_TRACK_OBJECT
+</SECTION>
+
+<SECTION>
+<FILE>ges-track-source</FILE>
+<TITLE>GESTrackSource</TITLE>
+GESTrackSource
+GESTrackSourceClass
+ges_track_source_new
+<SUBSECTION Standard>
+GES_TRACK_SOURCE
+GES_TRACK_SOURCE_CLASS
+GES_TRACK_SOURCE_GET_CLASS
+GES_TYPE_TRACK_SOURCE
+GES_IS_TRACK_SOURCE
+GES_IS_TRACK_SOURCE_CLASS
+ges_track_source_get_type
+</SECTION>
+
+<SECTION>
+<FILE>ges-timeline</FILE>
+<TITLE>GESTimeline</TITLE>
+GESTimeline
+GESTimelineClass
+ges_timeline_remove_layer
+ges_timeline_remove_track
+ges_timeline_save
+ges_timeline_add_layer
+ges_timeline_add_track
+ges_timeline_get_track_for_pad
+ges_timeline_load_from_uri
+ges_timeline_new
+<SUBSECTION Standard>
+ges_timeline_get_type
+GES_IS_TIMELINE
+GES_IS_TIMELINE_CLASS
+GES_TIMELINE
+GES_TIMELINE_CLASS
+GES_TIMELINE_GET_CLASS
+GES_TYPE_TIMELINE
+</SECTION>
+
+
+<SECTION>
+<FILE>ges-timeline-layer</FILE>
+<TITLE>GESTimelineLayer</TITLE>
+GESTimelineLayer
+GESTimelineLayerClass
+ges_timeline_layer_add_object
+ges_timeline_layer_new
+ges_timeline_layer_remove_object
+ges_timeline_layer_set_timeline
+<SUBSECTION Standard>
+ges_timeline_layer_get_type
+GES_IS_TIMELINE_LAYER
+GES_IS_TIMELINE_LAYER_CLASS
+GES_TIMELINE_LAYER
+GES_TIMELINE_LAYER_CLASS
+GES_TIMELINE_LAYER_GET_CLASS
+GES_TYPE_TIMELINE_LAYER
+</SECTION>
+
+
+<SECTION>
+<FILE>ges-timeline-object</FILE>
+<TITLE>GESTimelineObject</TITLE>
+GESTimelineObject
+GESTimelineObjectClass
+ges_timeline_object_set_inpoint
+ges_timeline_object_set_layer
+ges_timeline_object_set_priority
+ges_timeline_object_set_start
+ges_timeline_object_create_track_object
+ges_timeline_object_fill_track_object
+ges_timeline_object_new
+ges_timeline_object_release_track_object
+ges_timeline_object_set_duration
+<SUBSECTION Standard>
+GES_IS_TIMELINE_OBJECT
+GES_IS_TIMELINE_OBJECT_CLASS
+GES_TIMELINE_OBJECT
+GES_TIMELINE_OBJECT_CLASS
+GES_TIMELINE_OBJECT_GET_CLASS
+GES_TYPE_TIMELINE_OBJECT
+ges_timeline_object_get_type
+</SECTION>
+
+
+<SECTION>
+<FILE>ges-timeline-pipeline</FILE>
+<TITLE>GESTimelinePipeline</TITLE>
+GESTimelinePipeline
+GESTimelinePipelineClass
+ges_timeline_pipeline_add_timeline
+ges_timeline_pipeline_new
+<SUBSECTION Standard>
+ges_timeline_pipeline_get_type
+GES_TIMELINE_PIPELINE
+GES_TIMELINE_PIPELINE_CLASS
+GES_TIMELINE_PIPELINE_GET_CLASS
+GES_IS_TIMELINE_PIPELINE
+GES_IS_TIMELINE_PIPELINE_CLASS
+GES_TYPE_TIMELINE_PIPELINE
+</SECTION>
+
+
+<SECTION>
+<FILE>ges-timeline-source</FILE>
+<TITLE>GESTimelineSource</TITLE>
+GESTimelineSource
+GESTimelineSourceClass
+ges_timeline_source_new
+<SUBSECTION Standard>
+ges_timeline_source_get_type
+GES_IS_TIMELINE_SOURCE
+GES_IS_TIMELINE_SOURCE_CLASS
+GES_TIMELINE_SOURCE
+GES_TIMELINE_SOURCE_CLASS
+GES_TIMELINE_SOURCE_GET_CLASS
+GES_TYPE_TIMELINE_SOURCE
+</SECTION>
+
+
+<SECTION>
+<FILE>ges-timeline-transition</FILE>
+<TITLE>GESTimelineTransition</TITLE>
+GESTimelineTransition
+GESTimelineTransitionClass
+ges_timeline_transition_new
+<SUBSECTION Standard>
+GES_IS_TIMELINE_TRANSITION
+GES_IS_TIMELINE_TRANSITION_CLASS
+GES_TIMELINE_TRANSITION
+GES_TIMELINE_TRANSITION_CLASS
+GES_TIMELINE_TRANSITION_GET_CLASS
+GES_TYPE_TIMELINE_TRANSITION
+ges_timeline_transition_get_type
+</SECTION>
+
+
+<SECTION>
+<FILE>ges-custom-timeline-source</FILE>
+<TITLE>GESCustomTimelineSource</TITLE>
+GESCustomTimelineSource
+GESCustomTimelineSourceClass
+ges_custom_timeline_source_new
+<SUBSECTION Standard>
+ges_cust_timeline_src_get_type
+GES_CUSTOM_TIMELINE_SOURCE
+GES_CUSTOM_TIMELINE_SOURCE_CLASS
+GES_CUSTOM_TIMELINE_SOURCE_GET_CLASS
+GES_IS_CUSTOM_TIMELINE_SOURCE
+GES_IS_CUSTOM_TIMELINE_SOURCE_CLASS
+GES_TYPE_CUSTOM_TIMELINE_SOURCE
+</SECTION>
+
+
+<SECTION>
+<FILE>ges-simple-timeline-layer</FILE>
+<TITLE>GESSimpleTimelineLayer</TITLE>
+GESSimpleTimelineLayer
+GESSimpleTimelineLayerClass
+ges_simple_timeline_layer_add_object
+ges_simple_timeline_layer_move_object
+ges_simple_timeline_layer_new
+ges_simple_timeline_layer_remove_object
+<SUBSECTION Standard>
+ges_simple_timeline_layer_get_type
+GES_IS_SIMPLE_TIMELINE_LAYER
+GES_IS_SIMPLE_TIMELINE_LAYER_CLASS
+GES_SIMPLE_TIMELINE_LAYER
+GES_SIMPLE_TIMELINE_LAYER_CLASS
+GES_SIMPLE_TIMELINE_LAYER_GET_CLASS
+GES_TYPE_SIMPLE_TIMELINE_LAYER
+</SECTION>
+

docs/version.entities.in

@@ -0,0 +1,2 @@
+<!ENTITY GST_MAJORMINOR "@GST_MAJORMINOR@">
+<!ENTITY GES_VERSION "@VERSION@">