GNOME Bugzilla – Bug 639430
[PATCH] Enable querying for custom GParamSpec properties during GObject scan
Last modified: 2018-05-22 13:03:57 UTC
Created attachment 178236 [details] [review] [PATCH] Add support for custom property parsing as part of GObject scan Use a similar approach to the GTK+ support to enable documentation of custom properties as each GType is scanned. Extra properties to look for are defined in a property loader definition file, which specifies a GType filter, property lookup function, and property flag ("s" for style, "c" for child, "" for standard) for each property returned. For example: MX_TYPE_STYLABLE,mx_stylable_iface_list_properties,s (obviously requires mx_stylable_iface_list_properties function to exist, which I've currently suggested for Mx) The property loader file is parsed by gtkdoc-scangobj (passed in via a new --custom-properties option) and used to augment the args output function (in mx-scan.c) for each scanned type. Any GTypes being scanned which match the GType filter have the property lookup function called on them; any returned GParamSpecs are then parsed and added to the .args file for the matching class, with the flags set. It might also be possible to refactor some of the GTK+ args output code to make use of this approach. Patch is attached (against master).
Review of attachment 178236 [details] [review]: Thanks for coming up with this. It is indeed needed. I need to think a bit more about what the best approach would be. ::: gtkdoc-scangobj.in @@ +24,3 @@ # by compiling a small C program. CFLAGS and LDFLAGS must be # set appropriately before running this script. # fixed in git with some other spelling mistake. @@ +32,3 @@ +# +# GType (class or interface),property list function,property flags +# Hmm, I am trying to get rid of the external files that one needs to customize. This is one thing that people complain about. What I also wonder about is how this will get propagated. Lets assume have this extra-properties in lib-a, I am implementing lib-b linking against lib-a and inheriting from base-classes in lib-a. Maybe this file should be installed to <prefix>/share/gtk-doc/data/extensions/<libname> and gtkdocscanobj would automatically take those into account (but this would not work for you, as you won't have it installed yet). @@ +763,3 @@ + +foreach $line (@custom_property_loaders) { + <nitpick> s/line/loader/ would make the code easier to read below. </nitpick> @@ +1302,3 @@ + PropertyListFunc func, + const gchar *default_flags) +{ this could share code with output_object_args()
I agree that adding more files isn't ideal, and take your point about inheritance. On the plus side, making the files part of the project does mean that you can customise the gtk-doc output for any arbitrary library, without having to get those files into gtk-doc itself. I agree with the line/loader change. I borrowed much of the code from output_object_args(), and think it would be good to merge the two. I didn't touch that function as I didn't want to break any existing behaviour (I don't know enough about that code to feel confident in changing it).
As an additional request that might be solvable with this: GTK has a bunch of GParamSpecs for CSS properties that aren't bound to any GObject and I'd like to make gtk-doc generate a nice html file with documentation for those properties. So I'd like this to work without a GType, just with a list of properties. (This doesn't need to be easy, but it'd be nice if it's possible.)
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/12.