GNOME Bugzilla – Bug 793211
GtkWidget align and margin accessors have wrong annotations
Last modified: 2018-05-02 19:50:40 UTC
Downstream bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1435965 GTKWidget's align and margin accessor functions are annotated with GDK_AVAILABLE_IN_ALL, but are only available since 3.0. This affects at least: gtk_widget_get_halign gtk_widget_set_halign gtk_widget_get_valign gtk_widget_set_valign gtk_widget_get_margin_top gtk_widget_set_margin_top gtk_widget_get_margin_bottom gtk_widget_set_margin_bottom The following are already deprecated: gtk_widget_get_margin_left gtk_widget_set_margin_left gtk_widget_get_margin_right gtk_widget_set_margin_right
Created attachment 367940 [details] [review] gtkwidget: Fix annotations for align and margin accessors (3.22) None of them are available before 3.0. Patch for gtk-3-22.
Created attachment 367943 [details] [review] gtkwidget: Fix annotations for align and margin accessors None of them are available before 3.0.
Since you literally cannot mix 3.0 and 2.0, the "IN_ALL" annotation means "available since the first release of the current major API version". We recently did the same change for 4.0. What's the underlying issue you're trying to address?
The documentation changes are the important part, then.
The issue is that there are many more symbols that were added in GTK+ 3.0 and are not present in GTK+ 2.x, so annotating just a subset is not sufficient if we're considering the case of developers of a code base that includes both version N and version N + 1; or the case of developers porting from version N to version N + 1. We did intentionally drop the Since annotation for every symbol pre-dating 3.0, and for symbols introduced with 3.0, because from the perspective of a developer, all symbols in the shared library are available from 3.0 onwards, and you cannot mix 2.0 ABI with 3.0 ABI. We did the same when going from 3.x to 4.x, and we discussed this at the 2018 GTK Hackfest as well: https://wiki.gnome.org/Hackfests/GTK2018/Day2 ``` do we drop since 2/3 annotations from the docs, for 4.0 ? decision: yes, we only keep "since 4.0" around for new api ``` Of course, it's entirely possible we're wrong, and maybe we need a better solution.
From IRC: ``` 10:53 < heftig> i'd like to see a "available since" annotation on all symbols, but I understand it would be a significant effort to check all the existing symbols 10:54 < heftig> in the firefox case it's actually a giant hack letting the code run against either version at runtime 10:55 < heftig> so any symbol used needs to be sorted into a list of either "only gtk2", "only gtk3" or "both" 10:56 < heftig> it's just the third time in half a year a symbol was mistakenly put into the "both" list instead of the "only gtk3" list 10:56 < heftig> this time I just noticed the documentation didn't have a "Since: 3.0" 10:57 <@ebassi> That's a fair point; I'd be worried to see "available since 2.0" in gtk5, though; also because it requires creating indices for all the previous major API versions, and that usually slows down the build and makes the API reference a pain to deal with 10:58 < heftig> maybe just the docs, then 10:58 <@ebassi> But maybe we need a "available since 2.0/3.0" annotation, and an "available since 4.n/4.n+1" one 10:58 < heftig> as you said the annotations don't help and I just stumbled upon them after checking the docs ``` We may need a way to categorise symbols that were available from previous major versions, as part of the "porting" API; maybe we don't need "Since: major.minor" annotations, but just "Since major.0".
-- 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/issues/1027.