GNOME Bugzilla – Bug 719614
docs: add missing docs and fix errors
Last modified: 2013-12-03 00:16:35 UTC
When building the GStreamer documentation I see lots of existing, but missing, documentation. In these two patches I add the missing docs and fix some errors. Let me know if there is any issue with these or if you prefer me to separate something out.
Created attachment 263209 [details] [review] Proposed patch with cosmetic doc changes
Created attachment 263210 [details] [review] Proposed patch with slightly more invasive changes
Review of attachment 263209 [details] [review]: I went over these, and seems all correct.
Review of attachment 263210 [details] [review]: Typo in comment, GstOutputSelectorPad*Negoriation*Mode ::: docs/libs/gstreamer-libs-sections.txt @@ +85,2 @@ <SECTION> +<FILE>gstindex</FILE> I'm not sure if we should make this visible. Also, many are inside #if 0 #endif block, looks like GTK Doc does not detect it. Commented out: _new _comit _get_group _new_group _set_group _set_certainty _get_certainty _set_filter _set_filter_full _set_resolver _set_resolver_full _add_format _add_association _add_object ::: docs/plugins/gstreamer-plugins-sections.txt @@ +172,3 @@ GST_IS_QUEUE GST_QUEUE_CLASS +GST_QUEUE_CAST Maybe we could just put a skip on this one, after-all it's kind of legacy ? ::: gst/gstcontrolsource.c @@ +26,3 @@ * * The #GstControlSource is a base class for control value sources that could + * be used on an object to get timestamp-value pairs. A control source could be use <> to get ? Why do we need an object ? ::: gst/gstobject.c @@ +1137,3 @@ * or not. * + * This function is used to disable the controller on a property for to disable the *control bindings* on a property ?
> Typo in comment, GstOutputSelectorPad*Negoriation*Mode Fixed. > +<FILE>gstindex</FILE> > I'm not sure if we should make this visible. Also, many are inside #if 0 > #endif block, looks like GTK Doc does not detect it. I had a chat with __tim who removed it from the docs in 2011, and you are right GstIndex should not be part of the docs at all. Therefore I opted to not include the header at all when running gtk-doc. > +GST_QUEUE_CAST > Maybe we could just put a skip on this one, after-all it's kind of legacy ? Let's handle it the same way as GST_BIN_CAST, namely that it is part of the standard part of the sections-file and then it will not show up in the documentation (since there is no gtk-doc comment). I spoke briefly with wtay and he seemed to like this option. > + * be used on an object to get timestamp-value pairs. A control source > could be use <> to get ? Why do we need an object ? Fixed. > + * This function is used to disable the controller on a property for > to disable the *control bindings* on a property ? Fixed.
Created attachment 263235 [details] [review] Proposed patch with cosmetic doc changes
Created attachment 263236 [details] [review] Proposed patch with slightly more invasive changes
Pushed, many thanks: commit 49950e57ad5f6eadbbe9d45d0ab3f7f7b4ce7577 Author: Sebastian Rasmussen <sebras@hotmail.com> Date: Sat Nov 30 12:15:37 2013 +0100 docs: add missing docs, fixing doc errors * add many missing declarations to sections * GstController has been removed, update docs * skip GstIndex when generating documentation * rephrase so gtkdoc doesn't imagine return value * add missing argument description for gst_context_new() * document GstOutputSelectorPadNegotiationMode and move to header-file https://bugzilla.gnome.org/show_bug.cgi?id=719614 commit b40fa2b8c3485a8374186ca047622ab518e09485 Author: Sebastian Rasmussen <sebras@hotmail.com> Date: Sat Nov 30 14:52:40 2013 +0100 docs: cosmetic changes in references/decriptions * fix typo GstBufferFlag -> GstBufferFlags * fix typo GstFeatures -> GstCapsFeatures * fix typo GstAllocatorParams -> GstAllocationParams * fix typo GstContrlSources -> GstControlSource * do not refer to gstcheck as an object * make references gtk_init() and tcase_set_timeout() not be references * gst_element_get_pad() renamed gst_element_get_static_pad() * gst_clock_id_wait_async_full() renamed gst_clock_id_wait_async() * _drop_element() is really gst_queue_array_drop_element() * gst_pad_accept_caps() was removed, do not refer to it * separate GST_META_TAG_MEMORY_STR declaration from description * do not describe removed gst_collect_pads_collect() * correctly link to GstElementClass' virtual set_context() Fixes https://bugzilla.gnome.org/show_bug.cgi?id=719614 Not so keen on the GstOutputSelectorPadNegotiationMode thing, but pushed it for now. It's very confusing for people though to find these enums documented and then not have header files they can include to make use of them. I think it's another example of how gtk-doc doesn't work quite right for us with plugins yet. Anyway, that just so you don't go and go on a property enum documentation rampage for all the other modules ;)