The title question may not be clear, so I have an example: in GIMP public API, we have the class GimpPath which is a path item in the meaning of a vector object.
Now “path” is often used for meaning a path on file system too, and for instance, the utils function `gimp_path_parse() is about such a usage of “path”.
Unfortunately I realize that GObject Introspection associates this function to the GimpPath class mistakenly, which is weird (even if I guess the function will still work fine).
Is there an annotation to force gimp_path_parse() to be Gimp.path_parse (i.e. just a path_parse function under the Gimp module)? I searched in docs but couldn’t find this.
It’s kind of hard to do, because turning gimp_path_parse() into Gimp.path_parse() would also imply turning things like Gdk.RGBA.parse() into Gdk.rgba_parse(), which is definitely something we do not want.
We don’t have a not method annotation, at the moment, and introducing one is still not entirely enough.
The issue, here, is that the function should have been called gimp_parse_path() to begin with. This would have avoided the matching to the longest substring.
My suggestion to fix this issue:
introduce gimp_parse_path()
deprecate gimp_path_parse()
If you want to hide gimp_path_parse() from the introspection data, then you can surround its declaration with a check on the __GI_SCANNER__ symbol:
Yeah. I think it is completely fine that this association is made by default (both the Gimp.Path.parse() and Gdk.RGBA.parse()). So I’m really not advocating against this; just to have a voluntary way of opting out of it.
I guess it could be e.g. a (instrospect-as Gimp.path_parse) annotation? (or named something else; I’m not always the best to name things!)
Or maybe (not Gimp.Path) to use a similar naming as your (not method) proposed annotation, to explicitly say that this is not to be put into the Gimp.Path API.
Indeed. From reading the MR, it doesn’t look like the same issue either since Gimp.Path.parse is not considered a Gimp.Path object method either anyway, more like a class function. And there is no Gimp.Path argument (first one or otherwise!) into this function signature.
Sure. I don’t deny that this could have been caught earlier and renamed appropriately. To be fair, this function has existed in GIMP since forever (it has been introduced in 2000!), while we only started using GObject-Introspection for GIMP 3 in 2025.
Anyway, we could play a deprecation+renaming game of course, as you suggest, but I would really have preferred a way to annotate that it’s just not part of Gimp.Path API. Because other than for GObject-Introspection, this method name is not entirely wrong either and we are really trying to avoid breaking existing people scripts unnecessarily (well a deprecation does not break the script but adds some warning, which is annoying on its own).
Anyway I’ll think further, maybe do what you suggest, or maybe propose an annotation request, or maybe just nothing as time permits.
I’ll end in a completely unrelated question (sorry!) which was triggered by your last proposition:
We have one piece of code which is only compiled when building for macOS:
And that triggers this annoying warning twice when generating the GIR (on any platform):
[7/16] Generating libgimp/GimpUi-3.0.gir with a custom command (wrapped by meson to set env)
/home/jehan/dev/src/gimp/libgimp/gimpui.c:750: unexpected character `@'
/home/jehan/dev/src/gimp/libgimp/gimpui.c:750: unexpected character `@'
We have been looking for how to get rid of it (well not me much personally). When I saw your piece of code above, I hoped that wrapping in #ifndef __GI_SCANNER__ would work, but apparently not.
Is there a trick to hide such code from GIR tools and get back to a warning-less build!
P.S.: also to just hide a function from introspection data, why don’t you just suggest using (skip)?
This would have avoided the matching to the longest substring.
To be fair, this function has existed in GIMP since forever (it has been introduced in 2000!), while we only started using GObject-Introspection for GIMP 3 in 2025.
