Re: Signal argument names

[Owen Taylor <otaylor redhat com>]

Matthias Clasen <maclas gmx de> writes:

> On Thu, 2002-11-07 at 17:32, Owen Taylor wrote:
> > > I have this mostly working, see the attached patch. There are some
> > > complications, because we have to be careful to prefer the param names
> > > from source over those generated by gtkdoc-scangobj (those pesky argn),
> > > unlike normal functions, where we prefer the names from the templates
> > > over the source names (why ?). 
> > 
> > I think the idea is that it won't matter because the template
> > file names have to match the names found by gtkdoc-scan, or
> > gtkdoc-mktmpl will replace them when updating the template
> > files.
> > 
> > See, OutputParam() in gtkdoc-mktmpl
> 
> Yes. Unfortunately, gtkdoc-mktmpl can never get this right for signals,
> since it only has the artificially generated arg names from the
> gtk.signals file and the stuff already in the templates to choose from.
> To fix this, we would probably have to extend gtkdoc-scan to also parse
> signal declarations in headers and dump them (with meaningfull arg
> names) to gtk-decl.txt. Since this is a bit more work, I have instead
> modified gtkdoc-mkdb to prefer the c source arg names over template arg
> names (for signals only).

Yeah, I just was theorizing about why it was that way for function arguments;
I think the simple solution for symbols is right.
  
> Here is a new version of the patch, which additionally supports putting
> property documentation inline in the form:
> 
> /**
>  * GdkDisplayManager:default-display:
>  *
>  * The default display.
>  */
> 
> This will then be used instead of the blurb. Note that properties use a
> single : instead of :: to separate class and symbol. (I've just copied
> existing gtk-doc practice, don't know if it is really necessary -
> clashes with signals should be very rare...)

OK, I'm not sure that I ever expect people to write _two_ sets of docs
for their properties, but I guess it's good to be prepared :-)
 
> Do you have any proposal for the placement of these signal and property
> doc comments in the source ? Before class_init, after class_init, or
> even inside class_init, before the corresponding signal/property
> registrations ?

My tendendency would be to do them inside class_init() mixed with the
signal registrations. I think it is confusing to have to look multiple
places for information about a particular signal.

Regards,
                                        Owen