GNOME Bugzilla – Bug 676430
documentation fixes
Last modified: 2012-09-03 17:59:26 UTC
Created attachment 214501 [details] [review] patch implementing descrided doc fixes It would seem, that back when gdk-pixbuf was pulled out of gtk+, it *accidentally* lost GdkPixbuf Xlib documentation. This patch restores it and fixes a couple of typos. A few questions, though: - I know *very* little about gtk-doc, so I couldn't really tell what is the purpose of '<link linkend="GDK_PIXBUF_MODULE_FILE"><envar>GDK_PIXBUF_MODULE_FILE</envar>' in docs/reference/gdk-pixbuf/gdk-pixbuf-query-loaders.xml, besides causing a gtk-doc warning - as above, in quite a few in-source comments '&gdk-pixbuf;' construct is used; in in-tree xml sources, this expands to '<application>gdk-pixbuf</application>', but is not correctly expanded for in-source comments; in fact, in this patch I changed it in one place to simply 'gdk-pixbuf' , so that a proper link was generated; so, what form should it take in the other places ? - before the split, there was a section referring to reference/gdk-pixbuf/porting-from-imlib.sgml, perhaps it should be restored too ?
Review of attachment 214501 [details] [review]: Thanks for the patch. There are some comments below about gtk-doc syntax as well as a question. ::: contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.c @@ -475,3 @@ /** * xlib_rgb_set_verbose: - * @verbose: %True to be verbose We use %XXX to refer to constants like %TRUE and %FALSE. In this case I guess it refers to the XLib constant %True... ::: docs/reference/gdk-pixbuf/gdk-pixbuf.xml @@ -135,3 @@ - <title>Index of new symbols in 2.10</title> - <xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include> - </index> Is there any reason you are removing these? ::: gdk-pixbuf/gdk-pixbuf-animation.c @@ +548,3 @@ * If this function returns %FALSE, there's no need to update the animation * display, assuming the display had been rendered prior to advancing; + * if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf() good catch. ::: gdk-pixbuf/gdk-pixbuf.c @@ +765,3 @@ * @value: a nul-terminated string. * + * Attaches a key/value pair as an option to a #GdkPixbuf. If key already should be @key to refer to a parameter
The difference being that TRUE/FALSE are documented, True/False are not, just produce warnings. As for removal, that's simple - no new symbols added to GdkPixBuf then - it's just a leftover from common gtk+/gdk-pixbuf docs. The question about '<application>gdk-pixbuf</application>' stays open - I'm nearly sure my workaround isn't quite correct there.
Created attachment 218197 [details] [review] patch updated with @key
Review of attachment 218197 [details] [review]: I think this looks good now.