GNOME Bugzilla – Bug 605025
improve boxed types support
Last modified: 2018-05-22 13:03:27 UTC
1. Boxed types are inspectable enough to appear as derived from GBoxed in the hierarchy so they should be there. 2. The current handling of MY_TYPE_FOO and my_foo_get_type() for boxed types is to dump them both in the section file with --rebuild-sections and to let people do anything if they don't rebuild sections. This means e.g in GLib MY_TYPE_FOO tends to be listed, wheres Gtk+ docs do not indicate whether a plain old data type is available as boxed or not. MY_TYPE_FOO and my_foo_get_type() for boxed types probably should be put to <SUBSECTION Standard> when generating the section file. 3. Once they are excluded it would be nice to insert `MyFoo implements/is derived from/provides/is available as/... GBoxed' somewhere automatically. Or added small hierarchy GBoxed -> MyFoo as is done for objects. Not sure how to implement either. 4. Boxed types can be defined in different place than the original type. E.g. G_TYPE_HASH_TABLE is defined in gobject because, obviously, it cannot go into glib. Not sure what to do in this case.
Doesn't gtk-doc suffer from the same issue regarding GEnums and GFlags? We should probably starting with a patch that adds those to the tests and then refine how it should be handled.
Created attachment 150163 [details] [review] proof of concept patch Yes, the same can be done for enums and flags (and posssibly other derivable things if we still forgot some). The attached naïve scangobj patch is sufficient to make them appear in the global type hierarchy and in small type hierarchies in each file. Unfortunately, immediately the old element id clash problem pops up again: We have multiple definition of MyFooType and MyFooFlags for enums and flags now. Boxed types for some reason do not suffer this.
Created attachment 150164 [details] [review] proof of concept patch Sorry, wrong patch, it included unrelated changes.
Another problem is that is creates links to GBoxed, GFlags, GEnum in glib. That would be present only if glib docs were compiled with this patch as otherwise there is no link target 'GBoxed' or 'GFlags'.
Yeti, could you have a look at the patch attached to Bug #591950, it think thats about the same issue. Your patch is only changing gtkdoc-scangobj. WHat I wonder is how should we present boxed/enum/flags. Right now we have a separate page for gobjects and within we have subsection for class hierarchy, signals, properties, ... Most projects right now stuff boxed/enum/flags into the section of the class that introduces them. We can't keep them inside the object page and have subsections. We can't auto-move them to a new page either (as they would need their own block in -sections.txt file). If we move them in the autogenerated -section.txt file case, we would break the xrefs.
We have three related bugs: this, being a bit more expanded version of bug 591950, and bug 593282 about the name clashes. All three should be decided simultaneously as we need some consistent plan how to differentiate section names and types. It think it is OK to keep the boxed, enums and flags in the same section where they are now because they do not introduce new subsections. The only generated content they appear in is the type hierarchy (global and local).
Yeti, could you add a example to tests/gobject so that one can see the effect?
*** Bug 591950 has been marked as a duplicate of this bug. ***
G_TYPE_PARAM should be added too. Apart G_TYPE_VOID, all fundamental types are theoretically derivable, so I'd add all of them to the patch. The attached (dirty) program shows the derivable and deep_derivable flag of each fundamental type. Funny enough, came out G_TYPE_INTERFACE is not deep_derivable...
Created attachment 150315 [details] Showing the derivable and deep_derivable flags of each fundamental type
If its just about the hierarchy - I agree with nicola, we should include all fundamental derivable types.
Created attachment 150380 [details] [review] add all fundamental types to the class hierarchy Integate Nicolas idea into Davids patch. I also added a new section to the gobject test suite (already committed), that contains a boxed and a enum. It kind of works, but: gtk-doc: Building HTML ../xml/types.xml:40: element refsect2: validity error : ID GtkdocEnum already defined <refsect2 id="GtkdocEnum" role="enum"> gtk-doc: Fixing cross-references html/tester-GtkdocTypes.html:60: warning: no link for: 'GEnum' -> (GEnum). For the GEnum one has the classic enum in the docs (same for flags). What should we have in the docs for a boxed type. I think it is actually wrong of putting all those GTKDOC_TYPE_XXX to the standart section. Although gtkdoc could generate some default docs for those,
I got rid of the fixxref warnings. Problem with the ../xml/types.xml:40: element refsect2: validity error : ID GtkdocEnum already defined <refsect2 id="GtkdocEnum" role="enum"> is the issues with the namespaces (see Bug #593282). Like we add "-struct" to disambigue GtkWidget as an object type from struct GtkWidget, we need the same for enums/flags atleast.
*** Bug 642998 has been marked as a duplicate of this bug. ***
-- 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/10.