From: Thomas V. S. <th...@ap...> - 2005-10-31 15:26:49
|
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/ |