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 597865 - Move documentation from templates to inline comments
Move documentation from templates to inline comments
Status: RESOLVED FIXED
Product: gtk+
Classification: Platform
Component: Documentation
unspecified
Other All
: Normal enhancement
: ---
Assigned To: gtk-bugs
gtk-bugs
Depends on:
Blocks: 599599
 
 
Reported: 2009-10-09 00:33 UTC by Javier Jardón (IRC: jjardon)
Modified: 2011-04-18 00:14 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Move documentation from templates to inline comments: GtkAboutDialog (13.82 KB, patch)
2009-10-09 00:35 UTC, Javier Jardón (IRC: jjardon)
none Details | Review
Move documentation from templates to inline comments: GtkAboutDialog (13.71 KB, patch)
2009-10-14 01:25 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkAccelGroup (8.47 KB, patch)
2009-10-14 02:13 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkToolShell (1.73 KB, patch)
2009-10-15 00:21 UTC, Javier Jardón (IRC: jjardon)
none Details | Review
GtkMountOperation (2.51 KB, patch)
2009-10-15 00:22 UTC, Javier Jardón (IRC: jjardon)
accepted-commit_now Details | Review
GtkActivatable (2.55 KB, patch)
2009-10-15 00:22 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkAccesible (1.74 KB, patch)
2009-10-15 00:23 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkWidget (73.58 KB, patch)
2009-10-15 00:24 UTC, Javier Jardón (IRC: jjardon)
none Details | Review
GtkToolShell.v2 (2.18 KB, patch)
2009-10-15 01:50 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkMountOperation.v2 (2.83 KB, patch)
2009-10-15 02:05 UTC, Javier Jardón (IRC: jjardon)
needs-work Details | Review
GtkWidget.v2 (73.79 KB, patch)
2009-11-05 23:56 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkFileChooser (56.75 KB, patch)
2009-11-07 06:31 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkStock (46.46 KB, patch)
2009-11-08 07:21 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
gtktypeutils (34.58 KB, patch)
2009-11-12 04:39 UTC, Javier Jardón (IRC: jjardon)
none Details | Review
gtktypeutils.v2 (33.89 KB, patch)
2009-11-12 04:41 UTC, Javier Jardón (IRC: jjardon)
none Details | Review
GtkWindow (24.10 KB, patch)
2009-11-12 06:01 UTC, Javier Jardón (IRC: jjardon)
none Details | Review
GtkWindow (17.93 KB, patch)
2009-11-12 06:42 UTC, Javier Jardón (IRC: jjardon)
none Details | Review
GtkWindow.v2 (24.16 KB, patch)
2009-11-12 10:04 UTC, Javier Jardón (IRC: jjardon)
needs-work Details | Review
GtkNotebook (21.81 KB, patch)
2009-11-13 01:02 UTC, Javier Jardón (IRC: jjardon)
needs-work Details | Review
GtkWindow.v3 (24.16 KB, patch)
2009-12-01 01:42 UTC, Javier Jardón (IRC: jjardon)
needs-work Details | Review
GtkNotebook.v2 (23.42 KB, patch)
2009-12-01 03:32 UTC, Javier Jardón (IRC: jjardon)
needs-work Details | Review
GtkMountOperation.v3 (4.30 KB, patch)
2009-12-01 04:15 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkImage (16.42 KB, patch)
2009-12-18 01:05 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
GtkMessageDialog (10.64 KB, patch)
2009-12-18 04:15 UTC, Javier Jardón (IRC: jjardon)
needs-work Details | Review
GtkMessageDialog.v2 (10.55 KB, patch)
2009-12-21 06:10 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review
Move documentation to inline comments: GtkFileChooserButton (6.21 KB, patch)
2010-04-30 22:17 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFileChooserDialog (11.48 KB, patch)
2010-04-30 22:18 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFileChooserWidget (3.46 KB, patch)
2010-04-30 22:18 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFileFilter (5.94 KB, patch)
2010-04-30 22:19 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFileSelection (14.55 KB, patch)
2010-04-30 22:19 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFixed (8.71 KB, patch)
2010-04-30 22:19 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFontSelection (5.01 KB, patch)
2010-04-30 22:20 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFontSelectionDialog (4.91 KB, patch)
2010-04-30 22:21 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFontButton (4.60 KB, patch)
2010-04-30 23:45 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkColorSelection (7.03 KB, patch)
2010-05-01 00:51 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkColorSelectionDialog (6.41 KB, patch)
2010-05-01 00:51 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFrame (5.02 KB, patch)
2010-05-01 00:52 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: gtkgc (4.18 KB, patch)
2010-05-01 00:57 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHandleBox (11.82 KB, patch)
2010-05-01 00:57 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHButtonBox (6.93 KB, patch)
2010-05-01 03:26 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHFrame (3.87 KB, patch)
2010-05-01 03:26 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHScale (3.18 KB, patch)
2010-05-01 03:26 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHScrollbar (2.99 KB, patch)
2010-05-01 03:27 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHSeparator (3.46 KB, patch)
2010-05-01 03:27 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHSV (3.75 KB, patch)
2010-05-01 03:28 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkIconFactory (12.90 KB, patch)
2010-05-01 03:29 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkHPaned (2.59 KB, patch)
2010-05-01 03:30 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkIconTheme (14.51 KB, patch)
2010-05-01 03:38 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkIconView (13.87 KB, patch)
2010-05-01 03:43 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkIMContext (3.93 KB, patch)
2010-05-01 03:45 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkIMContextSimple (2.89 KB, patch)
2010-05-01 03:48 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkImageMenuItem (4.04 KB, patch)
2010-05-01 03:58 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkIMMultiContext (2.45 KB, patch)
2010-05-01 03:59 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkInvisible (2.75 KB, patch)
2010-05-01 06:10 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkItem (4.61 KB, patch)
2010-05-01 06:10 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkLabel (24.82 KB, patch)
2010-05-01 06:10 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkLayout (4.92 KB, patch)
2010-05-01 06:11 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkLinkButton (5.47 KB, patch)
2010-05-01 06:12 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkListStore (16.14 KB, patch)
2010-05-01 06:12 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: gtkmain (46.88 KB, patch)
2010-05-01 06:13 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: Gtkmenu (22.13 KB, patch)
2010-05-01 06:13 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkMenuBar (6.78 KB, patch)
2010-05-01 06:14 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkMenuItem (12.04 KB, patch)
2010-05-01 06:14 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkMenuShell (13.55 KB, patch)
2010-05-01 06:14 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkMenuToolButton (5.09 KB, patch)
2010-05-01 06:15 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkMisc (6.41 KB, patch)
2010-05-01 08:14 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkNotebook (19.00 KB, patch)
2010-05-01 08:15 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkObject (36.37 KB, patch)
2010-05-01 08:15 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellRendererAccel (3.54 KB, patch)
2010-05-01 09:15 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellRendererCombo (4.18 KB, patch)
2010-05-01 09:15 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellRendererPixbuf (4.87 KB, patch)
2010-05-01 09:15 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellRendererProgress (286.60 KB, patch)
2010-05-01 09:16 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellRendererSpin (4.01 KB, patch)
2010-05-01 09:17 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellRendererText (6.62 KB, patch)
2010-05-01 09:17 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellRendererToggle (3.88 KB, patch)
2010-05-01 09:18 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCellView (3.77 KB, patch)
2010-05-01 09:18 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCheckButton (4.88 KB, patch)
2010-05-01 09:19 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkCheckMenuItem (9.27 KB, patch)
2010-05-01 09:19 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkClipboard (21.40 KB, patch)
2010-05-01 09:20 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFileChooserDialog v2 (12.24 KB, patch)
2010-05-02 19:51 UTC, Garrett Regier
none Details | Review
Move documentation to inline comments: GtkFixed v2 (8.71 KB, patch)
2010-05-02 19:51 UTC, Garrett Regier
none Details | Review

Description Javier Jardón (IRC: jjardon) 2009-10-09 00:33:28 UTC
See http://live.gnome.org/GTK+/TaskAPIDocMigration for more info
Comment 1 Javier Jardón (IRC: jjardon) 2009-10-09 00:35:06 UTC
Created attachment 145090 [details] [review]
Move documentation from templates to inline comments: GtkAboutDialog
Comment 2 Javier Jardón (IRC: jjardon) 2009-10-14 01:25:56 UTC
Created attachment 145391 [details] [review]
Move documentation from templates to inline comments: GtkAboutDialog
Comment 3 Javier Jardón (IRC: jjardon) 2009-10-14 01:34:20 UTC
Comment on attachment 145391 [details] [review]
Move documentation from templates to inline comments: GtkAboutDialog

commit 588bec91211977b311d9f2c808d3ff241fa53c38
Comment 4 Javier Jardón (IRC: jjardon) 2009-10-14 02:13:17 UTC
Created attachment 145392 [details] [review]
GtkAccelGroup
Comment 5 Javier Jardón (IRC: jjardon) 2009-10-15 00:21:25 UTC
Created attachment 145463 [details] [review]
GtkToolShell
Comment 6 Javier Jardón (IRC: jjardon) 2009-10-15 00:22:03 UTC
Created attachment 145464 [details] [review]
GtkMountOperation
Comment 7 Javier Jardón (IRC: jjardon) 2009-10-15 00:22:47 UTC
Created attachment 145465 [details] [review]
GtkActivatable
Comment 8 Javier Jardón (IRC: jjardon) 2009-10-15 00:23:20 UTC
Created attachment 145466 [details] [review]
GtkAccesible
Comment 9 Javier Jardón (IRC: jjardon) 2009-10-15 00:24:08 UTC
Created attachment 145467 [details] [review]
GtkWidget
Comment 10 Matthias Clasen 2009-10-15 00:30:44 UTC
Comment on attachment 145392 [details] [review]
GtkAccelGroup

this looks good
Comment 11 Matthias Clasen 2009-10-15 00:33:07 UTC
Comment on attachment 145463 [details] [review]
GtkToolShell

This seems to be a pretty empty patch... would be nice to actually add some docs.
Comment 12 Matthias Clasen 2009-10-15 00:34:52 UTC
Comment on attachment 145464 [details] [review]
GtkMountOperation

Would be good to expand the intro a bit, and explain that GtkMountOperation handles showing password dialogs when necessary, etc.
Comment 13 Matthias Clasen 2009-10-15 00:40:38 UTC
Comment on attachment 145467 [details] [review]
GtkWidget

The conversion of the intro looks broken. All the empty lines will make gtk-doc insert </para><para> which will mess up your tags.
Comment 14 Javier Jardón (IRC: jjardon) 2009-10-15 01:15:22 UTC
Comment on attachment 145392 [details] [review]
GtkAccelGroup

commit ff76366652e455d19f9766966a186ff5f396bea2
Comment 15 Javier Jardón (IRC: jjardon) 2009-10-15 01:15:54 UTC
Comment on attachment 145465 [details] [review]
GtkActivatable

commit bd2dd7dc9e39e1e74209bafcbe5a53fc70b62f4f
Comment 16 Javier Jardón (IRC: jjardon) 2009-10-15 01:16:52 UTC
Comment on attachment 145466 [details] [review]
GtkAccesible

commit bd2dd7dc9e39e1e74209bafcbe5a53fc70b62f4f
Comment 17 Javier Jardón (IRC: jjardon) 2009-10-15 01:50:04 UTC
Created attachment 145473 [details] [review]
GtkToolShell.v2
Comment 18 Javier Jardón (IRC: jjardon) 2009-10-15 01:58:32 UTC
Comment on attachment 145473 [details] [review]
GtkToolShell.v2

commit df5ee2fa10d0d1b3bb067f6667ae1d4e5a5ee2d4
Comment 19 Javier Jardón (IRC: jjardon) 2009-10-15 02:05:43 UTC
Created attachment 145474 [details] [review]
GtkMountOperation.v2
Comment 20 Stefan Sauer (gstreamer, gtkdoc dev) 2009-11-05 21:37:16 UTC
Review of attachment 145467 [details] [review]:

::: gtk/gtkwidget.c
@@ +63,3 @@
+ * <para id="style-properties">
+ * <structname>GtkWidget</structname> introduces <firstterm>style
+ * properties</firstterm> - these are basically object properties that are stored

try to make that <refsect2 id="style-properties"> (don't forget the closing </refsect>). The add a simple introductory paragpah before, something along the lines of:
GtkWidget is the base class all widgets in gtk+ derive from. I manages the widget lifecycle, states and style.
Comment 21 Javier Jardón (IRC: jjardon) 2009-11-05 23:56:04 UTC
Created attachment 147056 [details] [review]
GtkWidget.v2
Comment 22 Javier Jardón (IRC: jjardon) 2009-11-07 06:31:34 UTC
Created attachment 147158 [details] [review]
GtkFileChooser
Comment 23 Javier Jardón (IRC: jjardon) 2009-11-08 07:21:41 UTC
Created attachment 147204 [details] [review]
GtkStock
Comment 24 Javier Jardón (IRC: jjardon) 2009-11-12 04:39:28 UTC
Created attachment 147531 [details] [review]
gtktypeutils
Comment 25 Javier Jardón (IRC: jjardon) 2009-11-12 04:41:58 UTC
Created attachment 147532 [details] [review]
gtktypeutils.v2
Comment 26 Javier Jardón (IRC: jjardon) 2009-11-12 06:01:12 UTC
Created attachment 147536 [details] [review]
GtkWindow

The patch need some additional doc in ::set-focus: and ::frame-event: . Any suggestions?
Comment 27 Javier Jardón (IRC: jjardon) 2009-11-12 06:42:53 UTC
Created attachment 147539 [details] [review]
GtkWindow
Comment 28 Javier Jardón (IRC: jjardon) 2009-11-12 10:04:00 UTC
Created attachment 147550 [details] [review]
GtkWindow.v2
Comment 29 Javier Jardón (IRC: jjardon) 2009-11-13 01:02:49 UTC
Created attachment 147623 [details] [review]
GtkNotebook

I've added some "Deprecated: 2.0" info
Some of the signal need a bit of documentation
Comment 30 Matthias Clasen 2009-11-27 22:11:25 UTC
Review of attachment 145474 [details] [review]:

::: gtk/gtkmountoperation.c
@@ +59,3 @@
  * SECTION:filesystem
  * @short_description: Functions for working with GIO
+ * @Title: Filesystem utilities

This part looks fine.

@@ -69,3 @@
-
-/**
- * GtkMountOperation:

But why are you removing this ? The intention here was to document the GtkMountOperation struct, not add to the long description.
Comment 31 Matthias Clasen 2009-11-27 22:16:47 UTC
Review of attachment 147056 [details] [review]:

It would be nice to complete some of the signal docs some more. But as far as the mechanical moving of docs goes, this looks ok, modulo the one capitalization change.

::: gtk/gtkwidget.c
@@ +61,3 @@
+ * @Title: GtkWidget
+ *
+ * GtkWidget is the base class all widgets in gtk+ derive from. It manages the

Should write GTK+ instead of gtk+ here.
Comment 32 Matthias Clasen 2009-11-27 22:23:50 UTC
Review of attachment 147550 [details] [review]:

::: gtk/gtkwindow.c
@@ +80,3 @@
+ *
+ * <object class="GtkAccelGroup" id="accelgroup1"/>
+ * ]]></programlisting>

This requires some testing... I'm not positive that gtk-doc will handle the CDATA construct correctly in doc comments, and the empty lines in the example will likely cause it to insert paragraph markup.
Comment 33 Matthias Clasen 2009-11-27 22:28:19 UTC
Review of attachment 147623 [details] [review]:

It would be good to at least mark the keybinding signals as such while moving the docs inline. See e.g. gtktextview.c for the quasi-standard text I've used for that elsewhere.

::: gtk/gtknotebook.c
@@ +95,3 @@
+ *   </child>
+ * </object>
+ * ]]></programlisting>

Again, I'm not confident that gtk-doc will handle this CDATA construct correctly. Needs testing...

@@ +199,3 @@
+ * GtkNotebookPage:
+ *
+ * The #GtkNotebookPage is an opaque implementation detail of #GtkNotebook.

I'd rather move GtkNotebookPage to the private section in gtk-section.txt. It really is not public api.
Comment 34 Javier Jardón (IRC: jjardon) 2009-11-28 02:02:01 UTC
Comment on attachment 147056 [details] [review]
GtkWidget.v2

Commited this patch with the gtk+ -> GTK+ fix

commit 0ef8f5256765526075f2a25eac056c6e753b1849
Comment 35 Javier Jardón (IRC: jjardon) 2009-11-28 02:06:19 UTC
Comment on attachment 147204 [details] [review]
GtkStock

commit 2040547d967550b3debc928c16113ec3f83b7650
Comment 36 Javier Jardón (IRC: jjardon) 2009-11-28 02:43:13 UTC
(In reply to comment #32)
> Review of attachment 147550 [details] [review]:
> 
> ::: gtk/gtkwindow.c
> @@ +80,3 @@
> + *
> + * <object class="GtkAccelGroup" id="accelgroup1"/>
> + * ]]></programlisting>
> 
> This requires some testing... I'm not positive that gtk-doc will handle the
> CDATA construct correctly in doc comments, and the empty lines in the example
> will likely cause it to insert paragraph markup.

Tested here and seems to work correctly (at least the html generated doc is ok).
The CDATA seems to work as a verbatim environment, so the empty lines are empty lines in the final doc. Anyway, I think is better delete the empty lines.
Comment 37 Javier Jardón (IRC: jjardon) 2009-12-01 01:42:39 UTC
Created attachment 148802 [details] [review]
GtkWindow.v3
Comment 38 Javier Jardón (IRC: jjardon) 2009-12-01 03:32:24 UTC
Created attachment 148803 [details] [review]
GtkNotebook.v2

Here a new patch with comments in keybinding signals.
Some of the parameters are a bit undocumented because I'm not very sure how these signals works.
Comment 39 Javier Jardón (IRC: jjardon) 2009-12-01 04:15:52 UTC
Created attachment 148804 [details] [review]
GtkMountOperation.v3
Comment 40 Javier Jardón (IRC: jjardon) 2009-12-18 01:05:43 UTC
Created attachment 149952 [details] [review]
GtkImage

A new patch. Tested here without any new error/warning
Comment 41 Javier Jardón (IRC: jjardon) 2009-12-18 04:15:22 UTC
Created attachment 149967 [details] [review]
GtkMessageDialog

Here a new patch.

I've changed the examples to use GTK_BUTTONS_OK instead GTK_BUTTONS_CLOSE to follow the HIG guidelines: http://library.gnome.org/devel/hig-book/stable/windows-alert.html.en
Comment 42 Matthias Clasen 2009-12-19 03:04:11 UTC
Comment on attachment 147158 [details] [review]
GtkFileChooser

Assuming you have verified that the docs still come out correctly after applying this, looks fine.
Comment 43 Matthias Clasen 2009-12-19 03:05:12 UTC
Review of attachment 147532 [details] [review]:

This is all deprecated. Do we really want to move it around before dropping it in 3.0 ?
Comment 44 Matthias Clasen 2009-12-19 03:08:29 UTC
Review of attachment 148802 [details] [review]:

::: gtk/gtkwindow.c
@@ +812,3 @@
+   * @window: the window which received the signal.
+   * @widget:
+   */

Empty doc comments like this are not really useful. If there is no content in the template, we can just leave this out until somebody gets around to document this signal.

@@ +829,3 @@
+   *
+   * Returns:
+   */

Same here.
Comment 45 Matthias Clasen 2009-12-19 03:14:38 UTC
Review of attachment 148803 [details] [review]:

::: gtk/gtknotebook.c
@@ +57,3 @@
+ * <term>#GtkContainer</term>
+ * <listitem><para>For functions that apply to every #GtkContainer</para></listitem>
+ * </varlistentry>

I prefer to do 'see also' as a simple list of links, instead of an explicit varlist. But in this case, the see_also seems entirely redundant, since it just points back at the parent class, which is already accessible in other way. I'd just remove it.

@@ +934,3 @@
+   * <link linkend="keybinding-signals">keybinding signal</link>.
+   *
+   * The default bindings for this signal are Home and End.

The docs for keybinding signals should have three pieces:

1) The quasi-standard xref to keybinding-signals

2) An explanation of the action that is triggered

3) The default bindings

You have 1) and 3) here, but miss 2)

@@ +953,3 @@
+   * <link linkend="keybinding-signals">keybinding signal</link>.
+   *
+   * The default binding for this signal is Space.

Here too.
Comment 46 Matthias Clasen 2009-12-19 03:16:13 UTC
Review of attachment 148804 [details] [review]:

Looks good.
Comment 47 Matthias Clasen 2009-12-19 03:17:21 UTC
Review of attachment 149952 [details] [review]:

Looks good.
Comment 48 Matthias Clasen 2009-12-19 03:19:58 UTC
Review of attachment 149967 [details] [review]:

::: gtk/gtkenums.h
@@ +218,3 @@
+ * Prebuilt sets of buttons for the dialog. If
+ * none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
+ * then call gtk_dialog_add_buttons().

Looks like a copy-paste error here. The same enum seems to be documented in gtkmessagedialog.h ?
Comment 49 Matthias Clasen 2009-12-19 03:20:19 UTC
Review of attachment 149967 [details] [review]:

err
Comment 50 Javier Jardón (IRC: jjardon) 2009-12-21 05:33:09 UTC
Comment on attachment 147158 [details] [review]
GtkFileChooser

commit 016fba99e78107765e51cd5c295757e197b599f3

Added some Gtk-Doc markup to improve cross-references
Comment 51 Javier Jardón (IRC: jjardon) 2009-12-21 05:35:24 UTC
Comment on attachment 149952 [details] [review]
GtkImage

commit e62e7f76c91f186054fc5714800f6d0b67c89f65
Comment 52 Javier Jardón (IRC: jjardon) 2009-12-21 05:35:55 UTC
Comment on attachment 148804 [details] [review]
GtkMountOperation.v3

commit 25e3329215a11190a4846dada95d8fd305ac74f8
Comment 53 Javier Jardón (IRC: jjardon) 2009-12-21 06:10:34 UTC
Created attachment 150153 [details] [review]
GtkMessageDialog.v2

> Looks like a copy-paste error here. The same enum seems to be documented in
> gtkmessagedialog.h ?

Yeah, sorry. Here a new patch
Comment 54 Javier Jardón (IRC: jjardon) 2010-04-21 03:59:39 UTC
Comment on attachment 150153 [details] [review]
GtkMessageDialog.v2

committed a bit improved patch in commit 95fd5011c2e7251f424e583237023a937e47303c
Comment 55 Garrett Regier 2010-04-30 22:17:46 UTC
Created attachment 160019 [details] [review]
Move documentation to inline comments: GtkFileChooserButton
Comment 56 Garrett Regier 2010-04-30 22:18:20 UTC
Created attachment 160020 [details] [review]
Move documentation to inline comments: GtkFileChooserDialog
Comment 57 Garrett Regier 2010-04-30 22:18:42 UTC
Created attachment 160021 [details] [review]
Move documentation to inline comments: GtkFileChooserWidget
Comment 58 Garrett Regier 2010-04-30 22:19:02 UTC
Created attachment 160022 [details] [review]
Move documentation to inline comments: GtkFileFilter
Comment 59 Garrett Regier 2010-04-30 22:19:25 UTC
Created attachment 160023 [details] [review]
Move documentation to inline comments: GtkFileSelection
Comment 60 Garrett Regier 2010-04-30 22:19:58 UTC
Created attachment 160024 [details] [review]
Move documentation to inline comments: GtkFixed
Comment 61 Garrett Regier 2010-04-30 22:20:22 UTC
Created attachment 160025 [details] [review]
Move documentation to inline comments: GtkFontSelection
Comment 62 Garrett Regier 2010-04-30 22:21:19 UTC
Created attachment 160026 [details] [review]
Move documentation to inline comments: GtkFontSelectionDialog
Comment 63 Garrett Regier 2010-04-30 23:45:03 UTC
Created attachment 160028 [details] [review]
Move documentation to inline comments: GtkFontButton
Comment 64 Garrett Regier 2010-05-01 00:51:31 UTC
Created attachment 160031 [details] [review]
Move documentation to inline comments: GtkColorSelection
Comment 65 Garrett Regier 2010-05-01 00:51:55 UTC
Created attachment 160032 [details] [review]
Move documentation to inline comments: GtkColorSelectionDialog
Comment 66 Garrett Regier 2010-05-01 00:52:14 UTC
Created attachment 160033 [details] [review]
Move documentation to inline comments: GtkFrame
Comment 67 Garrett Regier 2010-05-01 00:57:26 UTC
Created attachment 160034 [details] [review]
Move documentation to inline comments: gtkgc
Comment 68 Garrett Regier 2010-05-01 00:57:58 UTC
Created attachment 160035 [details] [review]
Move documentation to inline comments: GtkHandleBox
Comment 69 Garrett Regier 2010-05-01 03:26:03 UTC
Created attachment 160040 [details] [review]
Move documentation to inline comments: GtkHButtonBox
Comment 70 Garrett Regier 2010-05-01 03:26:23 UTC
Created attachment 160041 [details] [review]
Move documentation to inline comments: GtkHFrame
Comment 71 Garrett Regier 2010-05-01 03:26:42 UTC
Created attachment 160042 [details] [review]
Move documentation to inline comments: GtkHScale
Comment 72 Garrett Regier 2010-05-01 03:27:05 UTC
Created attachment 160044 [details] [review]
Move documentation to inline comments: GtkHScrollbar
Comment 73 Garrett Regier 2010-05-01 03:27:50 UTC
Created attachment 160045 [details] [review]
Move documentation to inline comments: GtkHSeparator
Comment 74 Garrett Regier 2010-05-01 03:28:20 UTC
Created attachment 160046 [details] [review]
Move documentation to inline comments: GtkHSV
Comment 75 Garrett Regier 2010-05-01 03:29:06 UTC
Created attachment 160047 [details] [review]
Move documentation to inline comments: GtkIconFactory
Comment 76 Garrett Regier 2010-05-01 03:30:19 UTC
Created attachment 160048 [details] [review]
Move documentation to inline comments: GtkHPaned
Comment 77 Garrett Regier 2010-05-01 03:38:11 UTC
Created attachment 160049 [details] [review]
Move documentation to inline comments: GtkIconTheme
Comment 78 Garrett Regier 2010-05-01 03:43:31 UTC
Created attachment 160050 [details] [review]
Move documentation to inline comments: GtkIconView
Comment 79 Garrett Regier 2010-05-01 03:45:28 UTC
Created attachment 160051 [details] [review]
Move documentation to inline comments: GtkIMContext
Comment 80 Garrett Regier 2010-05-01 03:48:42 UTC
Created attachment 160052 [details] [review]
Move documentation to inline comments: GtkIMContextSimple
Comment 81 Garrett Regier 2010-05-01 03:58:51 UTC
Created attachment 160053 [details] [review]
Move documentation to inline comments: GtkImageMenuItem
Comment 82 Garrett Regier 2010-05-01 03:59:24 UTC
Created attachment 160054 [details] [review]
Move documentation to inline comments: GtkIMMultiContext
Comment 83 Garrett Regier 2010-05-01 06:10:08 UTC
Created attachment 160060 [details] [review]
Move documentation to inline comments: GtkInvisible
Comment 84 Garrett Regier 2010-05-01 06:10:24 UTC
Created attachment 160061 [details] [review]
Move documentation to inline comments: GtkItem
Comment 85 Garrett Regier 2010-05-01 06:10:56 UTC
Created attachment 160062 [details] [review]
Move documentation to inline comments: GtkLabel
Comment 86 Garrett Regier 2010-05-01 06:11:42 UTC
Created attachment 160063 [details] [review]
Move documentation to inline comments: GtkLayout
Comment 87 Garrett Regier 2010-05-01 06:12:23 UTC
Created attachment 160064 [details] [review]
Move documentation to inline comments: GtkLinkButton
Comment 88 Garrett Regier 2010-05-01 06:12:52 UTC
Created attachment 160065 [details] [review]
Move documentation to inline comments: GtkListStore
Comment 89 Garrett Regier 2010-05-01 06:13:22 UTC
Created attachment 160066 [details] [review]
Move documentation to inline comments: gtkmain
Comment 90 Garrett Regier 2010-05-01 06:13:40 UTC
Created attachment 160067 [details] [review]
Move documentation to inline comments: Gtkmenu
Comment 91 Garrett Regier 2010-05-01 06:14:00 UTC
Created attachment 160068 [details] [review]
Move documentation to inline comments: GtkMenuBar
Comment 92 Garrett Regier 2010-05-01 06:14:20 UTC
Created attachment 160069 [details] [review]
Move documentation to inline comments: GtkMenuItem
Comment 93 Garrett Regier 2010-05-01 06:14:53 UTC
Created attachment 160070 [details] [review]
Move documentation to inline comments: GtkMenuShell
Comment 94 Garrett Regier 2010-05-01 06:15:21 UTC
Created attachment 160071 [details] [review]
Move documentation to inline comments: GtkMenuToolButton
Comment 95 Garrett Regier 2010-05-01 08:14:59 UTC
Created attachment 160073 [details] [review]
Move documentation to inline comments: GtkMisc
Comment 96 Garrett Regier 2010-05-01 08:15:28 UTC
Created attachment 160074 [details] [review]
Move documentation to inline comments: GtkNotebook
Comment 97 Garrett Regier 2010-05-01 08:15:58 UTC
Created attachment 160075 [details] [review]
Move documentation to inline comments: GtkObject
Comment 98 Garrett Regier 2010-05-01 09:15:04 UTC
Created attachment 160079 [details] [review]
Move documentation to inline comments: GtkCellRendererAccel
Comment 99 Garrett Regier 2010-05-01 09:15:25 UTC
Created attachment 160080 [details] [review]
Move documentation to inline comments: GtkCellRendererCombo
Comment 100 Garrett Regier 2010-05-01 09:15:55 UTC
Created attachment 160081 [details] [review]
Move documentation to inline comments: GtkCellRendererPixbuf
Comment 101 Garrett Regier 2010-05-01 09:16:32 UTC
Created attachment 160082 [details] [review]
Move documentation to inline comments: GtkCellRendererProgress
Comment 102 Garrett Regier 2010-05-01 09:17:17 UTC
Created attachment 160083 [details] [review]
Move documentation to inline comments: GtkCellRendererSpin
Comment 103 Garrett Regier 2010-05-01 09:17:48 UTC
Created attachment 160084 [details] [review]
Move documentation to inline comments: GtkCellRendererText
Comment 104 Garrett Regier 2010-05-01 09:18:17 UTC
Created attachment 160085 [details] [review]
Move documentation to inline comments: GtkCellRendererToggle
Comment 105 Garrett Regier 2010-05-01 09:18:37 UTC
Created attachment 160086 [details] [review]
Move documentation to inline comments: GtkCellView
Comment 106 Garrett Regier 2010-05-01 09:19:10 UTC
Created attachment 160087 [details] [review]
Move documentation to inline comments: GtkCheckButton
Comment 107 Garrett Regier 2010-05-01 09:19:37 UTC
Created attachment 160088 [details] [review]
Move documentation to inline comments: GtkCheckMenuItem
Comment 108 Garrett Regier 2010-05-01 09:20:08 UTC
Created attachment 160089 [details] [review]
Move documentation to inline comments: GtkClipboard
Comment 109 Tadej Borovšak 2010-05-01 23:11:31 UTC
Review of attachment 160020 [details] [review]:

This patch needs some serious cleaning, since in the current state, it produces invalid XML and DocBook and will probably fail to build HTML docs (haven't tested it though). Also, sample code sections should be enclosed in CDATA markers in order to avoid having to escape various symbols in source code and retain readability.
Comment 110 Tadej Borovšak 2010-05-01 23:20:52 UTC
Review of attachment 160022 [details] [review]:

Large chunk of docs has been lost during migration here (GtkFileFilterInfo structure, GtkFileFilterFlags enumeration and GtkFileFilterFunc documentation is lacking). Did changes to gtkfilefilter.h file got lost when producing this patch?
Comment 111 Tadej Borovšak 2010-05-01 23:25:31 UTC
Review of attachment 160023 [details] [review]:

GtkFileSelection has been deprecated in favor of GtkFileChooser* family of widgets/interface. Docs for deprecated widgets are not migrated.
Comment 112 Tadej Borovšak 2010-05-01 23:38:56 UTC
Review of attachment 160024 [details] [review]:

::: gtk/gtkfixed.c
@@ -32,0 +32,20 @@
+
+
+/**
... 17 more ...

<listitem> elements cannot hold text directly; text needs to be encapsulated by some other element (usually <para>).

::: gtk/gtkfixed.h
@@ -52,0 +52,9 @@
+/**
+ * GtkFixed:
+ * @children: a list of #GtkFixedChild elements, containing the child widgets and
... 6 more ...

Structure fields of widgets that are GSEALed are all considered private and should not be documented.
Comment 113 Garrett Regier 2010-05-02 19:51:10 UTC
Created attachment 160160 [details] [review]
Move documentation to inline comments: GtkFileChooserDialog v2
Comment 114 Garrett Regier 2010-05-02 19:51:48 UTC
Created attachment 160161 [details] [review]
Move documentation to inline comments: GtkFixed v2
Comment 115 Javier Jardón (IRC: jjardon) 2010-06-09 00:42:06 UTC
Comment on attachment 148802 [details] [review]
GtkWindow.v3

Obsolete by commit e17b9f282fb6cfb413de598350e273a68031994b
Comment 116 Javier Jardón (IRC: jjardon) 2010-06-09 04:45:37 UTC
Comment on attachment 160050 [details] [review]
Move documentation to inline comments: GtkIconView

Obsolete by commit e17b9f282fb6cfb413de598350e273a68031994b
Comment 117 André Klapper 2011-04-13 11:57:03 UTC
So how can this get any progress? Javier?
Comment 118 Javier Jardón (IRC: jjardon) 2011-04-18 00:14:53 UTC
All this is fixed now :)

This problem has been fixed in the development version. The fix will be available in the next major software release. Thank you for your bug report.