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

[Michael Smith]

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
> 
> are imho not very useful, as GtkDoc adds links to the type docs (GstFoo) inside 
> the prototye avove anyway.

Agreed, in this case it would be silly. If there are multiple parameters
with the same name, further clarification is appropriate, such as "The
source #GstFoo", etc.

However, where there is only a single #GstFoo, and it's essentially
acting as a "this" pointer in an OO language, it's not useful to add
more information, and is merely messy and grammatically ugly.

Mike