GNOME Bugzilla – Bug 597865
Move documentation from templates to inline comments
Last modified: 2011-04-18 00:14:53 UTC
See http://live.gnome.org/GTK+/TaskAPIDocMigration for more info
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.