After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 302556 - GtkTreeView widget signals are badly documented
GtkTreeView widget signals are badly documented
Status: RESOLVED FIXED
Product: gtk+
Classification: Platform
Component: Documentation
unspecified
Other Linux
: Normal normal
: Small fix
Assigned To: gtk-bugs
gtk-bugs
Depends on:
Blocks:
 
 
Reported: 2005-04-30 17:12 UTC by Stefan Sauer (gstreamer, gtkdoc dev)
Modified: 2006-05-31 19:18 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
signal docs (8.87 KB, patch)
2005-05-02 12:00 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
needs-work Details | Review
signal docs v2 (9.50 KB, patch)
2005-09-22 08:00 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
none Details | Review
signal docs v3 (3.49 KB, patch)
2006-05-28 14:07 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
none Details | Review

Description Stefan Sauer (gstreamer, gtkdoc dev) 2005-04-30 17:12:14 UTC
none of the signal has a description
most of the parameters are undocumented
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2005-05-02 12:00:02 UTC
Created attachment 45931 [details] [review]
signal docs

please review (watch out for '???' markers).
Comment 2 Matthias Clasen 2005-05-02 13:40:04 UTC
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.
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2005-09-22 07:59:15 UTC
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?
Comment 4 Stefan Sauer (gstreamer, gtkdoc dev) 2005-09-22 08:00:27 UTC
Created attachment 52492 [details] [review]
signal docs v2
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2006-04-12 21:02:13 UTC
can't we get at least those in which make sense? Its a pitty to let a patch bitrot, don't you think?
Comment 6 Kristian Rietveld 2006-05-27 21:12:44 UTC
Stefan asked me to look at this, but since I'm no good at docs I'll let Matthias decide.
Comment 7 Matthias Clasen 2006-05-27 21:31:37 UTC
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.
Comment 8 Stefan Sauer (gstreamer, gtkdoc dev) 2006-05-28 12:12:21 UTC
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?
Comment 9 Matthias Clasen 2006-05-28 12:32:44 UTC
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.
Comment 10 Stefan Sauer (gstreamer, gtkdoc dev) 2006-05-28 14:07:48 UTC
Created attachment 66369 [details] [review]
signal docs v3

remove docs for keybinding signalss for now, spell-check docs
Comment 11 Matthias Clasen 2006-05-31 19:18:16 UTC
Committed, after fixing up the parameter docs