GNOME Bugzilla – Bug 302556
GtkTreeView widget signals are badly documented
Last modified: 2006-05-31 19:18:16 UTC
none of the signal has a description most of the parameters are undocumented
Created attachment 45931 [details] [review] signal docs please review (watch out for '???' markers).
Index: gtktreeview.c =================================================================== RCS file: /cvs/gnome/gtk+/gtk/gtktreeview.c,v retrieving revision 1.452 diff -u -u -r1.452 gtktreeview.c --- gtktreeview.c 29 Apr 2005 18:50:03 -0000 1.452 +++ gtktreeview.c 2 May 2005 11:56:33 -0000 @@ -759,8 +759,15 @@ GTK_PARAM_READABLE)); /* Signals */ + /** + * GtkTreeView::set-scroll-adjustments: + * @arg1: hadjustment + * @arg2: vadjustment + * + * One or both scrollbar objects are changed. + */ Please use meaningful names for the arguments. Ideally just the names from the vfunc decl in the header. What has been changed here are the adjustments. + /** + * GtkTreeView::row-activated: + * @arg1: a tree path that points to the row + * @arg2: the tree view column that has the focus + * + * The given row has been selected. That signal is emitted when a double click + * on a row or if an un-editable row is selected and of of the keys: Space, + * Shift+Space, Return oe Enter is pressed. + */ The row has been activated, not selected. Sloppy language in this area just leads to confusion. + /** + * GtkTreeView::test-expand-row: + * @arg1: the tree iter of the row to expand + * @arg2: a tree path that points to the row + * + * The given row should be expanded (show child nodes). + * + * Returns: %TRUE to allow expansion, %FALSE to reject + */ I would be a bit more verbose here. E.g. The given row is about to be expanded. Use this signal if you need to control the expandability of individual rows. G_TYPE_NONE, 0); + /** + * GtkTreeView::move-cursor: + * @arg1: the type of movement + * @arg2: the number of steps + * + * ??? The position of the cursor is about to change. This (and the following G_SIGNAL_ACTION signals) are keybinding signals and not meant to be used by connecting handlers to them. We need to figure out how to properly document such signals. The important information here is that you can put something like bind "<ctrl>f" { "move-cursor" (logical-positions, 1) } into key theme rc files.
I've updated the patch. Regarding the G_SIGNAL_ACTION signals (about which I unfortunately know nothing about), why not documents them as you've said: /** * GtkTreeView::move-cursor: * @arg1: the type of movement * @arg2: the number of steps * * A keybindings signal that one does not use via g_signal_connect(). * It allows customisation of cursor movement via rc files, by * adding a line like: * bind "<ctrl>f" { "move-cursor" (logical-positions, 1) } * */ Does this rc-file entry look similar for all the signals? Are you able to provide the correction if I just add the skelelton, so that we can get the patch in?
Created attachment 52492 [details] [review] signal docs v2
can't we get at least those in which make sense? Its a pitty to let a patch bitrot, don't you think?
Stefan asked me to look at this, but since I'm no good at docs I'll let Matthias decide.
There are a bunch of typos like s/oe/or/ and s/emited/emitted/ Also, the action signals (those with G_SIGNAL_ACTION are keybinding signals and should not be documented like normal signals.
Okay, fixed the spelling errors locally, the remaining question is, what do we do with the G_SIGNAL_ACTION ? - document them like proposed in #3?
I think it may be better to get some gtk-doc support to group the action signals together in their own subsection, and add a Keybindings subsection in the rc files section, that explains the general concept and gives examples. I don't think we want to have an example of keybindings rc file syntax in the docs for every single keybinding signal. In short, lets get the docs for the regular signals in now, and figure out keybinding signals separately.
Created attachment 66369 [details] [review] signal docs v3 remove docs for keybinding signalss for now, spell-check docs
Committed, after fixing up the parameter docs