Created attachment 145090 [details] [review]
Move documentation from templates to inline comments: GtkAboutDialog

Created attachment 145391 [details] [review]
Move documentation from templates to inline comments: GtkAboutDialog

Comment on attachment 145391 [details] [review]
Move documentation from templates to inline comments: GtkAboutDialog

commit 588bec91211977b311d9f2c808d3ff241fa53c38

Created attachment 145392 [details] [review]
GtkAccelGroup

Created attachment 145463 [details] [review]
GtkToolShell

Created attachment 145464 [details] [review]
GtkMountOperation

Created attachment 145465 [details] [review]
GtkActivatable

Created attachment 145466 [details] [review]
GtkAccesible

Created attachment 145467 [details] [review]
GtkWidget

Comment on attachment 145392 [details] [review]
GtkAccelGroup

this looks good

Comment on attachment 145463 [details] [review]
GtkToolShell

This seems to be a pretty empty patch... would be nice to actually add some docs.

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 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 on attachment 145392 [details] [review]
GtkAccelGroup

commit ff76366652e455d19f9766966a186ff5f396bea2

Comment on attachment 145465 [details] [review]
GtkActivatable

commit bd2dd7dc9e39e1e74209bafcbe5a53fc70b62f4f

Comment on attachment 145466 [details] [review]
GtkAccesible

commit bd2dd7dc9e39e1e74209bafcbe5a53fc70b62f4f

Created attachment 145473 [details] [review]
GtkToolShell.v2

Comment on attachment 145473 [details] [review]
GtkToolShell.v2

commit df5ee2fa10d0d1b3bb067f6667ae1d4e5a5ee2d4

Created attachment 145474 [details] [review]
GtkMountOperation.v2

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.

Created attachment 147056 [details] [review]
GtkWidget.v2

Created attachment 147158 [details] [review]
GtkFileChooser

Created attachment 147204 [details] [review]
GtkStock

Created attachment 147531 [details] [review]
gtktypeutils

Created attachment 147532 [details] [review]
gtktypeutils.v2

Created attachment 147536 [details] [review]
GtkWindow

The patch need some additional doc in ::set-focus: and ::frame-event: . Any suggestions?

Created attachment 147539 [details] [review]
GtkWindow

Created attachment 147550 [details] [review]
GtkWindow.v2

Created attachment 147623 [details] [review]
GtkNotebook

I've added some "Deprecated: 2.0" info
Some of the signal need a bit of documentation

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.

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.

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.

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 on attachment 147056 [details] [review]
GtkWidget.v2

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

commit 0ef8f5256765526075f2a25eac056c6e753b1849

Comment on attachment 147204 [details] [review]
GtkStock

commit 2040547d967550b3debc928c16113ec3f83b7650

(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.

Created attachment 148802 [details] [review]
GtkWindow.v3

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.

Created attachment 148804 [details] [review]
GtkMountOperation.v3

Created attachment 149952 [details] [review]
GtkImage

A new patch. Tested here without any new error/warning

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 on attachment 147158 [details] [review]
GtkFileChooser

Assuming you have verified that the docs still come out correctly after applying this, looks fine.

Review of attachment 147532 [details] [review]:

This is all deprecated. Do we really want to move it around before dropping it in 3.0 ?

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.

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.

Review of attachment 148804 [details] [review]:

Looks good.

Review of attachment 149952 [details] [review]:

Looks good.

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 ?

Review of attachment 149967 [details] [review]:

err

Comment on attachment 147158 [details] [review]
GtkFileChooser

commit 016fba99e78107765e51cd5c295757e197b599f3

Added some Gtk-Doc markup to improve cross-references

Comment on attachment 149952 [details] [review]
GtkImage

commit e62e7f76c91f186054fc5714800f6d0b67c89f65

Comment on attachment 148804 [details] [review]
GtkMountOperation.v3

commit 25e3329215a11190a4846dada95d8fd305ac74f8

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 on attachment 150153 [details] [review]
GtkMessageDialog.v2

committed a bit improved patch in commit 95fd5011c2e7251f424e583237023a937e47303c

Created attachment 160019 [details] [review]
Move documentation to inline comments: GtkFileChooserButton

Created attachment 160020 [details] [review]
Move documentation to inline comments: GtkFileChooserDialog

Created attachment 160021 [details] [review]
Move documentation to inline comments: GtkFileChooserWidget

Created attachment 160022 [details] [review]
Move documentation to inline comments: GtkFileFilter

Created attachment 160023 [details] [review]
Move documentation to inline comments: GtkFileSelection

Created attachment 160024 [details] [review]
Move documentation to inline comments: GtkFixed

Created attachment 160025 [details] [review]
Move documentation to inline comments: GtkFontSelection

Created attachment 160026 [details] [review]
Move documentation to inline comments: GtkFontSelectionDialog

Created attachment 160028 [details] [review]
Move documentation to inline comments: GtkFontButton

Created attachment 160031 [details] [review]
Move documentation to inline comments: GtkColorSelection

Created attachment 160032 [details] [review]
Move documentation to inline comments: GtkColorSelectionDialog

Created attachment 160033 [details] [review]
Move documentation to inline comments: GtkFrame

Created attachment 160034 [details] [review]
Move documentation to inline comments: gtkgc

Created attachment 160035 [details] [review]
Move documentation to inline comments: GtkHandleBox

Created attachment 160040 [details] [review]
Move documentation to inline comments: GtkHButtonBox

Created attachment 160041 [details] [review]
Move documentation to inline comments: GtkHFrame

Created attachment 160042 [details] [review]
Move documentation to inline comments: GtkHScale

Created attachment 160044 [details] [review]
Move documentation to inline comments: GtkHScrollbar

Created attachment 160045 [details] [review]
Move documentation to inline comments: GtkHSeparator

Created attachment 160046 [details] [review]
Move documentation to inline comments: GtkHSV

Created attachment 160047 [details] [review]
Move documentation to inline comments: GtkIconFactory

Created attachment 160048 [details] [review]
Move documentation to inline comments: GtkHPaned

Created attachment 160049 [details] [review]
Move documentation to inline comments: GtkIconTheme

Created attachment 160050 [details] [review]
Move documentation to inline comments: GtkIconView

Created attachment 160051 [details] [review]
Move documentation to inline comments: GtkIMContext

Created attachment 160052 [details] [review]
Move documentation to inline comments: GtkIMContextSimple

Created attachment 160053 [details] [review]
Move documentation to inline comments: GtkImageMenuItem

Created attachment 160054 [details] [review]
Move documentation to inline comments: GtkIMMultiContext

Created attachment 160060 [details] [review]
Move documentation to inline comments: GtkInvisible

Created attachment 160061 [details] [review]
Move documentation to inline comments: GtkItem

Created attachment 160062 [details] [review]
Move documentation to inline comments: GtkLabel

Created attachment 160063 [details] [review]
Move documentation to inline comments: GtkLayout

Created attachment 160064 [details] [review]
Move documentation to inline comments: GtkLinkButton

Created attachment 160065 [details] [review]
Move documentation to inline comments: GtkListStore

Created attachment 160066 [details] [review]
Move documentation to inline comments: gtkmain

Created attachment 160067 [details] [review]
Move documentation to inline comments: Gtkmenu

Created attachment 160068 [details] [review]
Move documentation to inline comments: GtkMenuBar

Created attachment 160069 [details] [review]
Move documentation to inline comments: GtkMenuItem

Created attachment 160070 [details] [review]
Move documentation to inline comments: GtkMenuShell

Created attachment 160071 [details] [review]
Move documentation to inline comments: GtkMenuToolButton

Created attachment 160073 [details] [review]
Move documentation to inline comments: GtkMisc

Created attachment 160074 [details] [review]
Move documentation to inline comments: GtkNotebook

Created attachment 160075 [details] [review]
Move documentation to inline comments: GtkObject

Created attachment 160079 [details] [review]
Move documentation to inline comments: GtkCellRendererAccel

Created attachment 160080 [details] [review]
Move documentation to inline comments: GtkCellRendererCombo

Created attachment 160081 [details] [review]
Move documentation to inline comments: GtkCellRendererPixbuf

Created attachment 160082 [details] [review]
Move documentation to inline comments: GtkCellRendererProgress

Created attachment 160083 [details] [review]
Move documentation to inline comments: GtkCellRendererSpin

Created attachment 160084 [details] [review]
Move documentation to inline comments: GtkCellRendererText

Created attachment 160085 [details] [review]
Move documentation to inline comments: GtkCellRendererToggle

Created attachment 160086 [details] [review]
Move documentation to inline comments: GtkCellView

Created attachment 160087 [details] [review]
Move documentation to inline comments: GtkCheckButton

Created attachment 160088 [details] [review]
Move documentation to inline comments: GtkCheckMenuItem

Created attachment 160089 [details] [review]
Move documentation to inline comments: GtkClipboard

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.

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?

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.

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.

Created attachment 160160 [details] [review]
Move documentation to inline comments: GtkFileChooserDialog v2

Created attachment 160161 [details] [review]
Move documentation to inline comments: GtkFixed v2

Comment on attachment 148802 [details] [review]
GtkWindow.v3

Obsolete by commit e17b9f282fb6cfb413de598350e273a68031994b

Comment on attachment 160050 [details] [review]
Move documentation to inline comments: GtkIconView

Obsolete by commit e17b9f282fb6cfb413de598350e273a68031994b

So how can this get any progress? Javier?

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.