[gst-devel] API reference updating for 0.9 -- your help needed!

[Thomas Vander Stichele]

On Mon, 2005-10-31 at 13:54 +0100, Stefan Kost wrote:
> Hi Andy,
> > Hey all,
> > 
> -- snip --
> >   * Anyone else with CVS commit access but who does not feel
> >     comfortable reviewing content can help out greatly by making the
> >     existing docs more consistent. For example, change this:
> >       * @pad: the #GstPad to stop the task of
> >     to:
> >       * @pad: a #GstPad
> >     and the other guidelines listed in [1].
> I missed that discussion. Whats the rationale behint. Imagine a function
> gst_foo_copy(GstFoo *src, GstFoo *dst)
> 
> then docs saying
> * @src: a #GstFoo
> * @dst: a #GstFoo

Quoting from gtk-doc' s style-guide.txt:

Function Parameters
===================

For object-oriented code, denote the object parameter with 'a',
e.g. 'a #GHashTable'.

Use 'the' for the rest of the parameters.

so in your case it would be
@src: a #GstFoo
@dst: the #GstFoo to copy into

(for example)

> are imho not very useful, as GtkDoc adds links to the type docs (GstFoo) inside 
> the prototye avove anyway.

it seems to be recommended and done in glib and I think it's fine.
consistency matters in this case I think.

Thomas


Dave/Dina : future TV today ! - http://www.davedina.org/
<-*- thomas (dot) apestaart (dot) org -*->
I could do so much harm
I could do you no good
I'll leave a stain in your heart I would
<-*- thomas (at) apestaart (dot) org -*->
URGent, best radio on the net - 24/7 ! - http://urgent.fm/