GNOME Bugzilla – Bug 113645
Include signals in -undocumented.txt
Last modified: 2004-12-22 21:47:04 UTC
One of the things that I really miss when consulting gtk API docs is a description of when signal are emitted; what I mean is: each widget has a list of its signals, when you click on a signal the docs show you what the callback should look like. As far as I can see nothing tells you *when* such a signal is emitted; in many cases this is pretty obvious from the signal name (eg button-clicked etc), but in many others it's not (eg event-after just to name the one I was trying to understand today). What I'd like to see is something like button-clicked: the signal is emitted when the button is clicked (I know this is a stupid example ;) but you get the idea... )
I think this is just "document undocumented signals", which isn't all that useful of a bug report to have open, in my opinion. Changes were added to gtk-doc last fall to allow inline documentation of signals, which is how I think it should be done in general. See thread from: http://mail.gnome.org/archives/gtk-doc-list/2002-November/thread.html What would help though in trying to get the signal docs more complete would be to have them in gtk-undocumented.txt, so I've repurposed to the bug to that end.
Here is a patch which changes gtkdoc-mkdb to a) include signals and properties in the total number of symbols b) report undocumented signals and properties
Created attachment 16856 [details] [review] patch
Committed with some changes which were requested by Owen on gtk-doc-list@gnome.org