From e2de071d4242b370dd6fe64c0f20aa8a551b86c8 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Tue, 4 Jan 2005 18:13:51 +0000 Subject: [PATCH] quick shell oneliner to find undocumented members in docs/README more enumtypes cleanup activated documentation comme... Original commit message from CVS: quick shell oneliner to find undocumented members in docs/README more enumtypes cleanup activated documentation comments, now someone needs to document the enums :( --- ChangeLog | 11 ++++ docs/README | 8 ++- docs/gst/tmpl/gstplugin.sgml | 2 +- docs/gst/tmpl/gstscheduler.sgml | 4 +- docs/gst/tmpl/gstthread.sgml | 2 +- docs/random/ensonic/interfaces.txt | 9 +++ gst/gsterror.h | 94 ++++++++++++++++++++++++------ 7 files changed, 107 insertions(+), 23 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3322d44254..064e9a1c4e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2005-01-04 Stefan Kost + + * docs/README: + quick shell oneliner to find undocumented members + * docs/gst/tmpl/gstplugin.sgml: + * docs/gst/tmpl/gstscheduler.sgml: + * docs/gst/tmpl/gstthread.sgml: + more enumtypes cleanup + * gst/gsterror.h: + activated documentation comments, now someone needs to document the enums :( + 2005-01-03 Ronald S. Bultje * docs/manual/manual.xml: diff --git a/docs/README b/docs/README index c5254aaaca..87d61c237c 100644 --- a/docs/README +++ b/docs/README @@ -119,7 +119,10 @@ GTK-DOC NOTES - add all documented symbols to gstreamer-sections.txt in the proper section (default),, - document at least the Short_Description in tmpl/.sgml - - signals: document them properly in tmpl/.sgml (or better in the c-source) + - document symbols where they are definied, so that when one changes the + definition, the chaces are good that docs are updated. + - document functions, signals in the .c files + - document structs, typedefs, enums in the .h files * checklist: - make sure *-sections.txt has a set for each <FILE> @@ -134,6 +137,9 @@ GTK-DOC NOTES grep "_get_type" gstreamer-sections.txt | sort with the types in XXX.types to detect entries that are maybe missing + - gtk docs does not warns about empty member docs!, run + find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \; | wc -l + in the project root to find them * what happens during a gtk-doc build ? - headers are scanned based on $(MODULE).types diff --git a/docs/gst/tmpl/gstplugin.sgml b/docs/gst/tmpl/gstplugin.sgml index 3422c4fb94..7e5e7bdc88 100644 --- a/docs/gst/tmpl/gstplugin.sgml +++ b/docs/gst/tmpl/gstplugin.sgml @@ -56,7 +56,7 @@ The plugin loading errors @GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded @GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies -@GST_PLUGIN_ERROR_NAME_MISMATCH: +@GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file <!-- ##### STRUCT GstPlugin ##### --> <para> diff --git a/docs/gst/tmpl/gstscheduler.sgml b/docs/gst/tmpl/gstscheduler.sgml index e2ffbf5134..bb737169d4 100644 --- a/docs/gst/tmpl/gstscheduler.sgml +++ b/docs/gst/tmpl/gstscheduler.sgml @@ -25,8 +25,8 @@ This is a base class for custom schedulers. Flags for the scheduler </para> -@GST_SCHEDULER_FLAG_FIXED_CLOCK: The scheduler has a fixed clock -@GST_SCHEDULER_FLAG_NEW_API: +@GST_SCHEDULER_FLAG_FIXED_CLOCK: the scheduler works with a fixed clock +@GST_SCHEDULER_FLAG_NEW_API: the scheduler supports select and lock calls @GST_SCHEDULER_FLAG_LAST: subclasses can start numbering their flags starting from here. diff --git a/docs/gst/tmpl/gstthread.sgml b/docs/gst/tmpl/gstthread.sgml index dccf545aea..53de65a449 100644 --- a/docs/gst/tmpl/gstthread.sgml +++ b/docs/gst/tmpl/gstthread.sgml @@ -49,7 +49,7 @@ Flags about the current thread state @GST_THREAD_STATE_SPINNING: The thread is runnning @GST_THREAD_STATE_REAPING: The thread is ending -@GST_THREAD_STATE_WAITING: +@GST_THREAD_STATE_WAITING: The thread is waiting to be run again @GST_THREAD_FLAG_LAST: subclass use this to start their enumeration <!-- ##### FUNCTION gst_thread_new ##### --> diff --git a/docs/random/ensonic/interfaces.txt b/docs/random/ensonic/interfaces.txt index 275e1505b0..e0ba350932 100644 --- a/docs/random/ensonic/interfaces.txt +++ b/docs/random/ensonic/interfaces.txt @@ -62,6 +62,15 @@ $Id$ - a slower version with higher precission that can be used for off-line rendering * new interfaces for audio applications + * GST_TYPE_MULTI_VOICE + - control interface for elements that support multiple voices (in one output-pad) + - API: + gulong number_of_voices; + void add_voice(); + void remove_last_voice(); + gulong get_number_of_voices(); + - features + - plugin will initially have one voice and that one can not be deleted * GST_TYPE_MUSIC_GENERATOR - add hints so that application can use a element as an instrument - API: diff --git a/gst/gsterror.h b/gst/gsterror.h index 9ffac98751..7a18cfa9aa 100644 --- a/gst/gsterror.h +++ b/gst/gsterror.h @@ -34,8 +34,25 @@ G_BEGIN_DECLS * * Check GError API docs for rationale for naming. */ -/* Core errors are anything that can go wrong in or using - * the core GStreamer library */ +/** + * GstCoreError: + * @GST_CORE_ERROR_FAILED: + * @GST_CORE_ERROR_TOO_LAZY: + * @GST_CORE_ERROR_NOT_IMPLEMENTED: + * @GST_CORE_ERROR_STATE_CHANGE: + * @GST_CORE_ERROR_PAD: + * @GST_CORE_ERROR_THREAD: + * @GST_CORE_ERROR_SCHEDULER: + * @GST_CORE_ERROR_NEGOTIATION: + * @GST_CORE_ERROR_EVENT: + * @GST_CORE_ERROR_SEEK: + * @GST_CORE_ERROR_CAPS: + * @GST_CORE_ERROR_TAG: + * @GST_CORE_ERROR_NUM_ERRORS: + * + * Core errors are anything that can go wrong in or using + * the core GStreamer library + */ /* FIXME: should we divide in numerical blocks so we can easily add for example PAD errors later ? */ typedef enum @@ -53,11 +70,21 @@ typedef enum GST_CORE_ERROR_CAPS, GST_CORE_ERROR_TAG, GST_CORE_ERROR_NUM_ERRORS -} -GstCoreError; +} GstCoreError; -/* Library errors are for errors from the library being used by elements - initializing, closing, ... */ +/** + * GstLibraryError: + * @GST_LIBRARY_ERROR_FAILED: + * @GST_LIBRARY_ERROR_TOO_LAZY: + * @GST_LIBRARY_ERROR_INIT: + * @GST_LIBRARY_ERROR_SHUTDOWN: + * @GST_LIBRARY_ERROR_SETTINGS: + * @GST_LIBRARY_ERROR_ENCODE: + * @GST_LIBRARY_ERROR_NUM_ERRORS: + * + * Library errors are for errors from the library being used by elements + * initializing, closing, ... + */ typedef enum { GST_LIBRARY_ERROR_FAILED = 1, @@ -67,12 +94,29 @@ typedef enum GST_LIBRARY_ERROR_SETTINGS, GST_LIBRARY_ERROR_ENCODE, GST_LIBRARY_ERROR_NUM_ERRORS -} -GstLibraryError; +} GstLibraryError; -/* Resource errors are for anything external used by an element: - memory, files, network connections, process space, ... - They're typically used by source and sink elements */ +/** + * GstResourceError: + * @GST_RESOURCE_ERROR_FAILED: + * @GST_RESOURCE_ERROR_TOO_LAZY: + * @GST_RESOURCE_ERROR_NOT_FOUND: + * @GST_RESOURCE_ERROR_BUSY: + * @GST_RESOURCE_ERROR_OPEN_READ: + * @GST_RESOURCE_ERROR_OPEN_WRITE: + * @GST_RESOURCE_ERROR_OPEN_READ_WRITE: + * @GST_RESOURCE_ERROR_CLOSE: + * @GST_RESOURCE_ERROR_READ: + * @GST_RESOURCE_ERROR_WRITE: + * @GST_RESOURCE_ERROR_SEEK: + * @GST_RESOURCE_ERROR_SYNC: + * @GST_RESOURCE_ERROR_SETTINGS: + * @GST_RESOURCE_ERROR_NUM_ERRORS: + * + * Resource errors are for anything external used by an element: + * memory, files, network connections, process space, ... + * They're typically used by source and sink elements + */ typedef enum { GST_RESOURCE_ERROR_FAILED = 1, @@ -89,12 +133,27 @@ typedef enum GST_RESOURCE_ERROR_SYNC, GST_RESOURCE_ERROR_SETTINGS, GST_RESOURCE_ERROR_NUM_ERRORS -} -GstResourceError; +} GstResourceError; -/* Stream errors are for anything related to the stream being processed: - format errors, media type errors, ... - They're typically used by decoders, demuxers, converters, ... */ +/** + * GstStreamError: + * @GST_STREAM_ERROR_FAILED: + * @GST_STREAM_ERROR_TOO_LAZY: + * @GST_STREAM_ERROR_NOT_IMPLEMENTED: + * @GST_STREAM_ERROR_TYPE_NOT_FOUND: + * @GST_STREAM_ERROR_WRONG_TYPE: + * @GST_STREAM_ERROR_CODEC_NOT_FOUND: + * @GST_STREAM_ERROR_DECODE: + * @GST_STREAM_ERROR_ENCODE: + * @GST_STREAM_ERROR_DEMUX: + * @GST_STREAM_ERROR_MUX: + * @GST_STREAM_ERROR_FORMAT: + * @GST_STREAM_ERROR_NUM_ERRORS: + * + * Stream errors are for anything related to the stream being processed: + * format errors, media type errors, ... + * They're typically used by decoders, demuxers, converters, ... + */ typedef enum { GST_STREAM_ERROR_FAILED = 1, @@ -109,8 +168,7 @@ typedef enum GST_STREAM_ERROR_MUX, GST_STREAM_ERROR_FORMAT, GST_STREAM_ERROR_NUM_ERRORS -} -GstStreamError; +} GstStreamError; /* This should go away once we convinced glib people to register GError */ #define GST_TYPE_G_ERROR (gst_g_error_get_type ())