Thanks for the bug report, this should definitely be fixed.

If you feel adventurous or bored, you could make a patch yourself, by getting a checkout of gstreamer and modifying the file gst/gstpad.h - it needs a gtk-doc comment block above the #define GST_PAD_SET_PROXY that's similar to the stuff in GstPadFlags (just simpler, without the @ lines).

And then the GST_PAD_SET_PROXY_CAPS in docs/gst/gstreamer-sections.txt needs to be moved from the 'Standard' subsection up above the '<SUBSECTION Standard>'.

Hi, does this should be done for all macros in this section?

Yes

Created attachment 271985 [details] [review]
Patch to add documentation in some macros

Comment on attachment 271985 [details] [review]
Patch to add documentation in some macros

I made a patch with the required documentation, but I find two problems

1) I don't know how I should modify gstreamer-sections.txt

2) I can't find documentation about four macros:
GST_PAD_BLOCK_GET_COND
GST_PAD_BLOCK_WAIT
GST_PAD_BLOCK_SIGNAL
GST_PAD_BLOCK_BROADCAST

If someone can help me it would be great :)

Please review my patch and tell me if it need some corrections.

(In reply to comment #5)
> (From update of attachment 271985 [details] [review])
> I made a patch with the required documentation, but I find two problems
> 
> 1) I don't know how I should modify gstreamer-sections.txt

You manually add the symbols there, there's nothing to do it automatically.
 
> 2) I can't find documentation about four macros:
> GST_PAD_BLOCK_GET_COND
> GST_PAD_BLOCK_WAIT
> GST_PAD_BLOCK_SIGNAL
> GST_PAD_BLOCK_BROADCAST

I think those should not be in the docs at all, they should not really be used outside of gstpad.c.

Review of attachment 271985 [details] [review]:

Looks good mostly, thanks for the patch :)

::: gst/gstpad.h
@@ +755,3 @@
+ * @pad: a #GstPad
+ *
+ * Get parent element.

It's not necesarily an element, it could also be another pad or something completely different. Also mention that no locking happens here

@@ +801,3 @@
+ *
+ * Get the @pad activation function (#GstPadActivateFunction).
+ * This function is called when the pad is activated during the element

Instead of explaining all these functions here I think you can just link to the docs of the GstPadActivateFunction and the others

@@ +875,3 @@
+ * @pad: a #GstPad
+ *
+ * Return the pad's peer memeber. This memeber is a pointer to the linked @pad.

Typo (memeber) and mention that no locking happens here

Created attachment 273050 [details] [review]
Patch to add documentation for some macros

Created attachment 273051 [details] [review]
This patch for gstpad.h and gstreamer-sections.txt

Review of attachment 273050 [details] [review]:

Hi Felipe. Thanks for taking care of this. Just a few nits:

::: gst/gstpad.h
@@ +771,3 @@
+ * @pad: a #GstPad
+ *
+ * Get the @pad #GstPadTemplate. It describe the possible media types

describes

@@ +837,3 @@
+ *
+ * Get the #GstPadEventFunction from the given @pad.
+ * This is the function handle an event for the pad.

This function will handle the pad's events
Or, closer to your version:
This is the function handling events for the pad

@@ +881,3 @@
+ * @pad: a #GstPad
+ *
+ * Return true if the @pad direction is equals to GST_PAD_SRC.

Drop the "is"

@@ +888,3 @@
+ * @pad: a #GstPad
+ *
+ * Return true if the @pad direction is equals to GST_PAD_SINK

Drop the "is"

@@ +952,3 @@
+ *
+ * Check if the @pad should be reconfigured/renegotiated.
+ * The flag has to be unset manually after reconfiguration happened.

manually unset

@@ +966,3 @@
+ * @pad: a #GstPad
+ *
+ * Check if the given @pad is using fixed caps this means that

. This means ..

@@ +981,3 @@
+ * @pad: a #GstPad
+ *
+ * Check if the given @pad is set as proxy caps this meas that the default

as/to
. This
meas/means

@@ +1004,3 @@
+ * @pad: a #GstPad
+ *
+ * Check if the given @pad is set as proxy allocation this means

as/to
. This

@@ +1027,3 @@
+ * @pad: a #GstPad
+ *
+ * Check if the given @pad is proxy scheduling this means that the

proxying maybe, but I'd rather phrase it like the above ones
. This

Thanks for the patches! I've pushed this now, with typos fixed (but I got a bit carried away and fleshed it out a little here and there, so apologies if I introduced more in your name). Sorry it took so long.

 commit d17438d5fd321daec4adbeb28a8fb5d5e07298dc
 Author: Showayb Zahda <showayb.zahda@axis.com>
 Date:   Sat Apr 26 17:02:18 2014 +0100

    docs: add docs for various GstPad macros
    
    https://bugzilla.gnome.org/show_bug.cgi?id=723652

Comment on attachment 273051 [details] [review]
This patch for gstpad.h and gstreamer-sections.txt

Pushed with changes.

PS: it would be great if you could provide a patch in 'git format-patch' format next time, that makes it easier for us to apply and saves us the typing of your name, e-mail and the commit message.

Ok, for the next time I use the 'git format-patch' and thanks for fix the typos

Hrm, it looks like I actually attributed the patch to the wrong person. I'm very sorry Felipe!

Fixed now.

Thanks!