GNOME Bugzilla – Bug 679160
Support stability gtk-doc tag
Last modified: 2015-02-07 16:57:55 UTC
It would be very nice if g-ir-scanner could embed information from the stability GTK-Doc tag in the GIR so that Vala could make use of the information.
Created attachment 217653 [details] [review] scanner: support stability tag
Review of attachment 217653 [details] [review]: Needs a test added to tests/scanner/regress.h; otherwise looks OK. Though I don't quite understand the special casing for ": ".
Created attachment 217661 [details] [review] scanner: support stability tag (In reply to comment #2) > Review of attachment 217653 [details] [review]: > > Needs a test added to tests/scanner/regress.h; otherwise looks OK. Though I Done. I couldn't find a test for deprecated or since either, so I added a function which tests all three. > don't quite understand the special casing for ": ". Neither do I, removed.
Review of attachment 217661 [details] [review]: One thing we should probably do is validate the tag. From gtk-doc's "sub ParseStabilityLevel", it looks like it can be one of "Stable", "Unstable" or "Private". Though honestly...what are people actually using this for? For "Private", I much prefer prefixing private symbols with "_" and using libtool's -export-symbols-regex to ensure they're not exported.
(In reply to comment #4) > Though honestly...what are people actually using this for? For "Private", I > much prefer prefixing private symbols with "_" and using libtool's > -export-symbols-regex to ensure they're not exported. one possible usage for Unstable is to mark unstable sections of the API that require a #define to be used, e.g. CLUTTER_ENABLE_EXPERIMENTAL_API, and that can change between minor development cycles.
(In reply to comment #4) > Review of attachment 217661 [details] [review]: > > One thing we should probably do is validate the tag. From gtk-doc's "sub > ParseStabilityLevel", it looks like it can be one of "Stable", "Unstable" or > "Private". The GTK-Doc manual states that they "recommend the use of one of these terms", not that they require it. So it seems that it /can/ be anything, but probably /should/ be one of those values. > Though honestly...what are people actually using this for? For "Private", I > much prefer prefixing private symbols with "_" and using libtool's > -export-symbols-regex to ensure they're not exported. I'm not sure anyone is actually using this right now... I can't recall ever actually seeing this in the wild. But Emmanuele's example is a good example of what it could be used for, and the reason all this came up is because Stef Walter wanted to annotate certain APIs in libsecret as experimental. If this gets into G-I I'll submit patches for libsecret, clutter, and probably a few other projects, to add "Stability: Unstable" to experimental symbols. Vala's current plan is to integrate it with a Version attribute which is currently being worked on (bug #678912), so we'll just check to see if it is "Unstable" and, if so, add [Version (experimental = true)]. Then we can emit a warning unless --enable-experimental is passed to valac. As for "Private", I do not think that means what you think it means: "Private — An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways." -- http://developer.gnome.org/gtk-doc-manual/stable/gtk-doc-manual.html So something like gdk_display_open_default_libgtk_only.
Created attachment 218479 [details] [review] scanner: support stability tag Updated version which will emit a warning for unknown values, and not write them to the GIR.
Review of attachment 218479 [details] [review]: Looks good.
commit 368d72e61740cb318647296ff39495ad32fbe4d3 Author: Evan Nemerson <evan@coeus-group.com> Date: Tue Jul 10 13:59:23 2012 -0700 scanner: support stability tag https://bugzilla.gnome.org/show_bug.cgi?id=679160
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]