Commit 21e56edf authored by Stefan Kost's avatar Stefan Kost
Browse files

put symbols in the sections.txt into the right sections (so that we dont get...

put symbols in the sections.txt into the right sections (so that we dont get wrong undocumented symbols) added TITLE ...

Original commit message from CVS:
put symbols in the sections.txt into the right sections (so that we dont get wrong undocumented symbols)
added TITLE tags where they were missing
fixed section names so that gtk-doc introspection works
fixed typos in api docs and docbook docs
added some thoughts about new interfaces (to personal notes)
parent e5a3b3f3
......@@ -87,6 +87,14 @@ HOW THE BUILD SYSTEM IS SET UP
* ps and pdf are built in the current dir, in one file
DOCBOOK NOTES
=============
* spell checking with aspell
* aspell -b -c --mode=sgml --lang=en <file>.xml
unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
GTK-DOC NOTES
=============
......@@ -108,10 +116,21 @@ GTK-DOC NOTES
- add both an entity and use the entity in gstreamer-docs.sgml
- add a new section to gstreamer-sections.txt
- add all documented symbols to gstreamer-sections.txt in the proper section
(default),<SUBSECTION Standard>,<SUBSECTION Private>
- document at least the Short_Description in tmpl/.sgml
- signals: document them properly in tmpl/.sgml (or better in the c-source)
- signals: document them properly in tmpl/.sgml
* checklist:
- make sure -sections.txt has a <TITLE> set for each <FILE>
- the title should be named like the type, when it gets registered
(otherwise gtkdoc introspection fails)
- for clarity name the file like the title, but all lowercase
* what to do when trying to improve the docs
- compare the output of
grep "_get_type" gstreamer-sections.txt | sort
with the types in XXX.types to detect entries that
are maybe missing
* what happens during a gtk-doc build ?
- headers are scanned based on $(MODULE).types
......@@ -120,12 +139,9 @@ GTK-DOC NOTES
where the module name is $(MODULE)
$(MODULE)-sections.txt is created if it doesn't exist yet (it should),
as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt
and .args, .hierarchy and .signals files are created
gtkdoc-scan is called
(FIXME: why is there gstreamer.types.in and gst-plugins.types.in ?)
* Possible errors and how to fix them
- Warning: multiple "IDs" for constraint linkend: gst-tag-register.
- check if gst_tag_register is listed more than once in -sections.txt
......@@ -156,3 +172,4 @@ RANDOM THINGS I'VE LEARNED
xsltproc has a --path option (that xmlto doesn't use yet), but it
resolves single files to $(specified_path)/$(srcdir)/$(file)
For now, we need to hack around it by copying xml to the build dir.
......@@ -17,8 +17,8 @@
<!ENTITY GstEvent SYSTEM "xml/gstevent.xml">
<!ENTITY GstFormat SYSTEM "xml/gstformat.xml">
<!ENTITY GstIndex SYSTEM "xml/gstindex.xml">
<!ENTITY GstImplementsInterface SYSTEM "xml/gstimplementsinterface.xml">
<!ENTITY GstInfo SYSTEM "xml/gstinfo.xml">
<!ENTITY GstInterface SYSTEM "xml/gstinterface.xml">
<!ENTITY GstLog SYSTEM "xml/gstlog.xml">
<!ENTITY GstMemChunk SYSTEM "xml/gstmemchunk.xml">
<!ENTITY GstObject SYSTEM "xml/gstobject.xml">
......@@ -35,7 +35,7 @@
<!ENTITY GstStructure SYSTEM "xml/gststructure.xml">
<!ENTITY GstSystemClock SYSTEM "xml/gstsystemclock.xml">
<!ENTITY GstTag SYSTEM "xml/gsttag.xml">
<!ENTITY GstTagInterface SYSTEM "xml/gsttaginterface.xml">
<!ENTITY GstTagSetter SYSTEM "xml/gsttagsetter.xml">
<!ENTITY GstThread SYSTEM "xml/gstthread.xml">
<!ENTITY GstTrace SYSTEM "xml/gsttrace.xml">
<!ENTITY GstTypeFind SYSTEM "xml/gsttypefind.xml">
......@@ -70,10 +70,12 @@
<chapter id="gstreamer">
<title>GStreamer Core Library</title>
<para>libgstreamer-0.8.so provides all the core GStreamer services,
including initialization, plugin management and types, as
well as the object hierarchy that defines elements and bins, along
with some more specialized elements.</para>
<para>
libgstreamer-&GST_MAJORMINOR;.so provides all the core GStreamer services,
including initialization, plugin management and types,
as well as the object hierarchy that defines elements and bins,
along with some more specialized elements.
</para>
&Gst;
&GstBin;
......@@ -89,7 +91,7 @@ with some more specialized elements.</para>
&GstFormat;
&GstIndex;
&GstInfo;
&GstInterface;
&GstImplementsInterface;
&GstObject;
&GstPad;
&GstParse;
......@@ -105,7 +107,7 @@ with some more specialized elements.</para>
&GstStructure;
&GstSystemClock;
&GstTag;
&GstTagInterface;
&GstTagSetter;
&GstThread;
&GstTypeFind;
&GstUri;
......@@ -118,6 +120,7 @@ with some more specialized elements.</para>
<chapter id="gstreamer-support">
<title>GStreamer Core Support</title>
<para>
Theses elements support the gstreamer core and applications using it.
</para>
&GstAtomic;
......@@ -126,6 +129,7 @@ with some more specialized elements.</para>
</chapter>
<!--
FIXME: why is this commented out
<chapter id="element-types">
<title>GStreamer Standard Elements</title>
......
<SECTION>
<FILE>gstbin</FILE>
GstBinFlags
<TITLE>GstBin</TITLE>
GstBin
GstBinFlags
gst_bin_new
gst_bin_add
gst_bin_add_many
......@@ -19,17 +20,20 @@ gst_bin_auto_clock
gst_bin_sync_children_state
gst_bin_child_state_change
<SUBSECTION Standard>
GstBinClass
GST_BIN
GST_IS_BIN
GST_TYPE_BIN
gst_bin_get_type
GST_BIN_CLASS
GST_IS_BIN_CLASS
GST_BIN_GET_CLASS
<SUBSECTION Private>
gst_bin_get_type
</SECTION>
<SECTION>
<FILE>gstbuffer</FILE>
<TITLE>GstBuffer</TITLE>
GstBuffer
GstBufferFreeDataFunc
GST_BUFFER_TRACE_NAME
......@@ -79,11 +83,13 @@ gst_buffer_default_copy
GST_BUFFER
GST_IS_BUFFER
GST_TYPE_BUFFER
<SUBSECTION Private>
gst_buffer_get_type
</SECTION>
<SECTION>
<FILE>gstcaps</FILE>
<TITLE>GstCaps</TITLE>
GST_CAPS_FLAGS_ANY
GST_CAPS_ANY
GST_CAPS_NONE
......@@ -136,11 +142,13 @@ gst_caps_subtract
GST_CAPS
GST_IS_CAPS
GST_TYPE_CAPS
<SUBSECTION Private>
gst_caps_get_type
</SECTION>
<SECTION>
<FILE>gstclock</FILE>
<TITLE>GstClock</TITLE>
GstClock
GstClockTime
GstClockTimeDiff
......@@ -168,7 +176,6 @@ GST_CLOCK_ENTRY_STATUS
GstClockReturn
GstClockFlags
GST_CLOCK_FLAGS
<TITLE>GstClock</TITLE>
gst_clock_set_speed
gst_clock_get_speed
gst_clock_set_resolution
......@@ -194,10 +201,11 @@ GstClockClass
GST_CLOCK
GST_IS_CLOCK
GST_TYPE_CLOCK
gst_clock_get_type
GST_CLOCK_CLASS
GST_IS_CLOCK_CLASS
GST_CLOCK_GET_CLASS
<SUBSECTION Private>
gst_clock_get_type
</SECTION>
<SECTION>
......@@ -227,6 +235,7 @@ GST_PAD_IS_CONNECTED
<SECTION>
<FILE>gstdata</FILE>
<TITLE>GstData</TITLE>
GST_DATA
GST_DATA_TYPE
GST_DATA_FLAGS
......@@ -253,13 +262,14 @@ gst_data_unref
<SUBSECTION Standard>
GST_DATA_FLAG_SET
GST_DATA_FLAG_IS_SET
<SUBSECTION Private>
gst_data_get_type
</SECTION>
<SECTION>
<FILE>gstelement</FILE>
GstElement
GstElementClass
GST_TYPE_ELEMENT
GstElementDetails
GST_ELEMENT_DETAILS
GST_IS_ELEMENT_DETAILS
......@@ -273,7 +283,6 @@ GST_STATE_PAUSED_TO_PLAYING
GST_STATE_PLAYING_TO_PAUSED
GST_STATE_PAUSED_TO_READY
GST_STATE_READY_TO_NULL
GST_ELEMENT_CLASS
GST_ELEMENT_QUERY_TYPE_FUNCTION
GST_ELEMENT_FORMATS_FUNCTION
GST_ELEMENT_EVENT_MASK_FUNCTION
......@@ -374,7 +383,6 @@ gst_element_get_factory
gst_element_get_managing_bin
gst_element_no_more_pads
<TITLE>GstElementFactory</TITLE>
gst_element_factory_get_type
gst_element_register
gst_element_factory_find
gst_element_factory_get_element_type
......@@ -391,23 +399,29 @@ gst_element_factory_make
gst_element_factory_can_src_caps
gst_element_factory_can_sink_caps
GstElementFactory
GstElementFactoryClass
GST_TYPE_ELEMENT_FACTORY
GST_ELEMENT_FACTORY
GST_ELEMENT_FACTORY_CLASS
GST_IS_ELEMENT_FACTORY
GST_IS_ELEMENT_FACTORY_CLASS
<SUBSECTION Standard>
GstElementClass
GST_ELEMENT
GST_IS_ELEMENT
GST_TYPE_ELEMENT
gst_element_get_type
GST_ELEMENT_CLASS
GST_IS_ELEMENT_CLASS
GST_ELEMENT_GET_CLASS
GstElementFactoryClass
GST_ELEMENT_FACTORY
GST_IS_ELEMENT_FACTORY
GST_ELEMENT_FACTORY_CLASS
GST_IS_ELEMENT_FACTORY_CLASS
<SUBSECTION Private>
gst_element_get_type
gst_element_factory_get_type
</SECTION>
<SECTION>
<FILE>gstevent</FILE>
<TITLE>GstEvent</TITLE>
GST_TYPE_EVENT
GstEvent
GstEventType
GST_EVENT_ANY
GST_EVENT_TRACE_NAME
......@@ -438,7 +452,6 @@ GST_EVENT_DISCONT_OFFSET_LEN
GST_EVENT_SIZE_FORMAT
GST_EVENT_SIZE_VALUE
GST_EVENT_RATE_VALUE
GstEvent
gst_event_new
gst_event_ref
gst_event_ref_by_count
......@@ -456,7 +469,7 @@ gst_event_new_flush
<SUBSECTION Standard>
GST_EVENT
GST_IS_EVENT
GST_TYPE_EVENT
<SUBSECTION Private>
gst_event_get_type
</SECTION>
......@@ -507,15 +520,8 @@ gst_index_entry_copy
gst_index_entry_free
gst_index_entry_assoc_map
GST_TYPE_INDEX_FACTORY
GST_INDEX_FACTORY
GST_IS_INDEX_FACTORY
GST_INDEX_FACTORY_CLASS
GST_IS_INDEX_FACTORY_CLASS
GST_INDEX_FACTORY_GET_CLASS
<TITLE>GstIndexFactory</TITLE>
GstIndexFactory
GstIndexFactoryClass
gst_index_factory_get_type
gst_index_factory_new
gst_index_factory_destroy
gst_index_factory_find
......@@ -526,14 +532,24 @@ GstIndexClass
GST_INDEX
GST_IS_INDEX
GST_TYPE_INDEX
gst_index_get_type
GST_INDEX_CLASS
GST_IS_INDEX_CLASS
GST_INDEX_GET_CLASS
GstIndexFactoryClass
GST_INDEX_FACTORY
GST_IS_INDEX_FACTORY
GST_INDEX_FACTORY_CLASS
GST_IS_INDEX_FACTORY_CLASS
GST_INDEX_FACTORY_GET_CLASS
<SUBSECTION Private>
gst_index_get_type
gst_index_factory_get_type
</SECTION>
<SECTION>
<FILE>gstinterface</FILE>
<FILE>gstimplementsinterface</FILE>
<TITLE>GstImplementsInterface</TITLE>
GST_TYPE_IMPLEMENTS_INTERFACE
GstImplementsInterface
GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_CAST
GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_TYPE
......@@ -541,21 +557,22 @@ gst_element_implements_interface
gst_implements_interface_cast
gst_implements_interface_check
<SUBSECTION Standard>
GstImplementsInterfaceClass
GST_IMPLEMENTS_INTERFACE
GST_IS_IMPLEMENTS_INTERFACE
GST_TYPE_IMPLEMENTS_INTERFACE
gst_implements_interface_get_type
GST_IMPLEMENTS_INTERFACE_CLASS
GST_IS_IMPLEMENTS_INTERFACE
GST_IS_IMPLEMENTS_INTERFACE_CLASS
GST_IMPLEMENTS_INTERFACE_GET_CLASS
<SUBSECTION Private>
gst_implements_interface_get_type
</SECTION>
<SECTION>
<FILE>gstobject</FILE>
GST_OBJECT_CLASS
xmlNodePtr
GstObjectFlags
<TITLE>GstObject</TITLE>
GstObject
GST_TYPE_OBJECT
GstObjectFlags
GST_FLAGS
GST_FLAG_IS_SET
GST_FLAG_SET
......@@ -585,36 +602,28 @@ gst_object_get_path_string
gst_class_signal_connect
gst_class_signal_emit_by_name
<SUBSECTION Standard>
GstObjectClass
GST_OBJECT
GST_IS_OBJECT
GST_TYPE_OBJECT
gst_object_get_type
GST_OBJECT_CLASS
GST_IS_OBJECT_CLASS
GST_OBJECT_GET_CLASS
<SUBSECTION Private>
gst_object_get_type
</SECTION>
<SECTION>
<FILE>gstpad</FILE>
GstPad
GstPadClass
GstRealPad
GstGhostPad
GstRealPadClass
GstGhostPadClass
GST_IS_PAD_FAST
GST_PAD_CLASS
GstPadTemplate
GST_TYPE_PAD
GST_TYPE_REAL_PAD
GST_IS_REAL_PAD
GST_IS_REAL_PAD_FAST
GST_IS_REAL_PAD_CLASS
GST_REAL_PAD
GST_REAL_PAD_CLASS
GST_TYPE_GHOST_PAD
GST_IS_GHOST_PAD
GST_IS_GHOST_PAD_FAST
GST_IS_GHOST_PAD_CLASS
GST_GHOST_PAD
GST_GHOST_PAD_CLASS
GST_IS_PAD_FAST
GstStaticPadTemplate
GstPadLink
GstPadLinkReturn
......@@ -684,10 +693,6 @@ GST_PAD_CAN_PULL
GST_PAD_IS_SRC
GST_PAD_IS_SINK
GST_TYPE_PAD_TEMPLATE
GST_PAD_TEMPLATE
GST_PAD_TEMPLATE_CLASS
GST_IS_PAD_TEMPLATE
GST_IS_PAD_TEMPLATE_CLASS
GstPadPresence
GST_PAD_TEMPLATE_NAME_TEMPLATE
GST_PAD_TEMPLATE_DIRECTION
......@@ -697,8 +702,6 @@ GstPadTemplateFlags
GST_PAD_TEMPLATE_IS_FIXED
<TITLE>GstPadTemplate</TITLE>
GST_STATIC_PAD_TEMPLATE
gst_real_pad_get_type
gst_ghost_pad_get_type
gst_pad_new
gst_pad_new_from_template
gst_pad_custom_new
......@@ -788,18 +791,37 @@ gst_pad_add_probe
gst_pad_remove_probe
gst_pad_load_and_link
gst_ghost_pad_new
gst_pad_template_get_type
gst_pad_template_new
gst_static_pad_template_get
gst_pad_template_get_caps
gst_pad_template_get_caps_by_name
gst_ghost_pad_save_thyself
<SUBSECTION Standard>
GstPadClass
GST_PAD
GST_IS_PAD
GST_TYPE_PAD
gst_pad_get_type
GST_PAD_CLASS
GST_IS_PAD_CLASS
GstGhostPadClass
GST_GHOST_PAD
GST_IS_GHOST_PAD
GST_GHOST_PAD_CLASS
GST_IS_GHOST_PAD_CLASS
GstRealPadClass
GST_REAL_PAD
GST_IS_REAL_PAD
GST_REAL_PAD_CLASS
GST_IS_REAL_PAD_CLASS
GstPadTemplateClass
GST_PAD_TEMPLATE
GST_IS_PAD_TEMPLATE
GST_PAD_TEMPLATE_CLASS
GST_IS_PAD_TEMPLATE_CLASS
<SUBSECTION Private>
gst_pad_get_type
gst_real_pad_get_type
gst_ghost_pad_get_type
gst_pad_template_get_type
</SECTION>
<SECTION>
......@@ -812,10 +834,11 @@ GstPipelineClass
GST_PIPELINE
GST_IS_PIPELINE
GST_TYPE_PIPELINE
gst_pipeline_get_type
GST_PIPELINE_CLASS
GST_IS_PIPELINE_CLASS
GST_PIPELINE_GET_CLASS
<SUBSECTION Private>
gst_pipeline_get_type
</SECTION>
<SECTION>
......@@ -837,25 +860,27 @@ GstPluginFeatureClass
GST_PLUGIN_FEATURE
GST_IS_PLUGIN_FEATURE
GST_TYPE_PLUGIN_FEATURE
gst_plugin_feature_get_type
GST_PLUGIN_FEATURE_CLASS
GST_IS_PLUGIN_FEATURE_CLASS
GST_PLUGIN_FEATURE_GET_CLASS
<SUBSECTION Private>
gst_plugin_feature_get_type
</SECTION>
<SECTION>
<FILE>gstqueue</FILE>
<TITLE>GstQueue</TITLE>
GstQueue
GstQueueClass
GstQueueSize
<SUBSECTION Standard>
GstQueueClass
GST_QUEUE
GST_IS_QUEUE
GST_TYPE_QUEUE
gst_queue_get_type
GST_QUEUE_CLASS
GST_IS_QUEUE_CLASS
<SUBSECTION Private>
gst_queue_get_type
</SECTION>
<SECTION>
......@@ -895,16 +920,16 @@ GstRegistryClass
GST_REGISTRY
GST_IS_REGISTRY
GST_TYPE_REGISTRY
gst_registry_get_type
GST_REGISTRY_CLASS
GST_IS_REGISTRY_CLASS
GST_REGISTRY_GET_CLASS
<SUBSECTION Private>
gst_registry_get_type
</SECTION>
<SECTION>
<FILE>gstscheduler</FILE>
GstScheduler
GstSchedulerClass
GstSchedulerFlags
GST_SCHEDULER_PARENT
GST_SCHEDULER_STATE
......@@ -934,16 +959,9 @@ gst_scheduler_get_clock
gst_scheduler_auto_clock
gst_scheduler_show
GST_TYPE_SCHEDULER_FACTORY
GST_SCHEDULER_FACTORY
GST_IS_SCHEDULER_FACTORY
GST_SCHEDULER_FACTORY_CLASS
GST_IS_SCHEDULER_FACTORY_CLASS
GST_SCHEDULER_FACTORY_GET_CLASS
GST_SCHEDULER_DEFAULT_NAME
<TITLE>GstSchedulerFactory</TITLE>
GstSchedulerFactory
GstSchedulerFactoryClass
gst_scheduler_factory_get_type
gst_scheduler_factory_new
gst_scheduler_factory_destroy
gst_scheduler_factory_find
......@@ -952,13 +970,22 @@ gst_scheduler_factory_make
gst_scheduler_factory_set_default_name
gst_scheduler_factory_get_default_name
<SUBSECTION Standard>
GstSchedulerClass
GST_SCHEDULER
GST_IS_SCHEDULER
GST_TYPE_SCHEDULER
gst_scheduler_get_type
GST_SCHEDULER_CLASS
GST_IS_SCHEDULER_CLASS
GST_SCHEDULER_GET_CLASS
GstSchedulerFactoryClass
GST_SCHEDULER_FACTORY
GST_IS_SCHEDULER_FACTORY
GST_SCHEDULER_FACTORY_CLASS
GST_IS_SCHEDULER_FACTORY_CLASS
GST_SCHEDULER_FACTORY_GET_CLASS
<SUBSECTION Private>
gst_scheduler_get_type
gst_scheduler_factory_get_type
</SECTION>
<SECTION>
......@@ -1000,6 +1027,7 @@ gst_structure_from_string
GST_STRUCTURE
GST_IS_STRUCTURE
GST_TYPE_STRUCTURE
<SUBSECTION Private>
gst_structure_get_type
</SECTION>
......@@ -1118,11 +1146,13 @@ GST_TAG_ALBUM_PEAK
<SUBSECTION Standard>
GST_TAG_FLAG_IS_VALID
GST_TAG_MODE_IS_VALID
<SUBSECTION Private>
gst_tag_list_get_type
</SECTION>
<SECTION>
<FILE>gsttaginterface</FILE>
<FILE>gsttagsetter</FILE>
<TITLE>GstTagSetter</TITLE>
GstTagSetter
GstTagSetterIFace
gst_tag_setter_merge
......@@ -1137,9 +1167,10 @@ gst_tag_setter_get_merge_mode
GST_TAG_SETTER
GST_IS_TAG_SETTER
GST_TYPE_TAG_SETTER
gst_tag_setter_get_type
GST_TAG_SETTER_CLASS
GST_TAG_SETTER_GET_IFACE
<SUBSECTION Private>
gst_tag_setter_get_type
</SECTION>
<SECTION>
......@@ -1156,14 +1187,16 @@ GstThreadClass
GST_THREAD
GST_IS_THREAD
GST_TYPE_THREAD
gst_thread_get_type
GST_THREAD_CLASS
GST_IS_THREAD_CLASS
GST_THREAD_GET_CLASS
<SUBSECTION Private>
gst_thread_get_type
</SECTION>
<SECTION>
<FILE>gsttypefind</FILE>
<TITLE>GstTypeFind</TITLE>
GstTypeFind
GstTypeFindFunction
GstTypeFindProbability
......@@ -1182,22 +1215,19 @@ GstTypeFindFactoryClass
GST_TYPE_FIND_FACTORY
GST_IS_TYPE_FIND_FACTORY
GST_TYPE_TYPE_FIND_FACTORY
gst_type_find_factory_get_type
GST_TYPE_FIND_FACTORY_CLASS
GST_IS_TYPE_FIND_FACTORY_CLASS
GST_TYPE_FIND_FACTORY_GET_CLASS
<SUBSECTION Private>
gst_type_find_factory_get_type
</SECTION>
<SECTION>
<FILE>gsturi</FILE>
GstURIType
GST_TYPE_URI_HANDLER
GST_URI_HANDLER
GST_IS_URI_HANDLER
GST_URI_HANDLER_GET_INTERFACE
GST_URI_HANDLER_CLASS
GstURIHandler
GstURIHandlerInterface
GST_URI_TYPE_IS_VALID
gst_uri_protocol_is_valid
gst_uri_is_valid
gst_uri_get_protocol
......@@ -1210,7 +1240,12 @@ gst_uri_handler_get_uri
gst_uri_handler_set_uri
gst_uri_handler_new_uri
<SUBSECTION Standard>
GST_URI_TYPE_IS_VALID
GstURIHandlerInterface
GST_URI_HANDLER
GST_IS_URI_HANDLER
GST_URI_HANDLER_CLASS
GST_URI_HANDLER_GET_INTERFACE
<SUBSECTION Private>
gst_uri_handler_get_type
</SECTION>
......@@ -1233,10 +1268,11 @@ GstXMLClass
GST_XML
GST_IS_XML
GST_TYPE_XML
gst_xml_get_type
GST_XML_CLASS
GST_IS_XML_CLASS
GST_XML_GET_CLASS
<SUBSECTION Private>
gst_xml_get_type
</SECTION>